diff options
| author | Scott Rifenbark <srifenbark@gmail.com> | 2018-05-17 09:32:22 -0700 |
|---|---|---|
| committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2018-05-24 17:16:36 +0100 |
| commit | 368474d7409fd5ae8f8cf8aa08dd0c4d14a4f575 (patch) | |
| tree | d7b6082870b06c154e1b02a898acc93a21af5e81 /documentation/dev-manual/dev-manual-common-tasks.xml | |
| parent | 9a37a3d568a04319cece45edfa04e787e06c4399 (diff) | |
| download | poky-368474d7409fd5ae8f8cf8aa08dd0c4d14a4f575.tar.gz | |
dev-manual: Removed "newbie" chapter.
This chapter only had the stuff about submitting a defect against
YP and making a change to YP. I moved that information into the
common tasks chapter as it is "how-to" information. Removal of this
chapter alse required that the mega-manual.xml file be updated to
not include the chapter.
(From yocto-docs rev: 4421b1585c21a6f7862525ba972f7e765626066e)
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
| -rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 627 |
1 files changed, 627 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 9e8dd5fa92..fe1bfba6cf 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml | |||
| @@ -13783,6 +13783,633 @@ | |||
| 13783 | </section> | 13783 | </section> |
| 13784 | </section> | 13784 | </section> |
| 13785 | 13785 | ||
| 13786 | <section id='making-changes-to-the-yocto-project'> | ||
| 13787 | <title>Making Changes to the Yocto Project</title> | ||
| 13788 | |||
| 13789 | <para> | ||
| 13790 | Because the Yocto Project is an open-source, community-based | ||
| 13791 | project, you can effect changes to the project. | ||
| 13792 | This section presents procedures that show you how to submit | ||
| 13793 | a defect against the project and how to submit a change. | ||
| 13794 | </para> | ||
| 13795 | |||
| 13796 | <section id='submitting-a-defect-against-the-yocto-project'> | ||
| 13797 | <title>Submitting a Defect Against the Yocto Project</title> | ||
| 13798 | |||
| 13799 | <para> | ||
| 13800 | Use the Yocto Project implementation of | ||
| 13801 | <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink> | ||
| 13802 | to submit a defect (bug) against the Yocto Project. | ||
| 13803 | For additional information on this implementation of Bugzilla see the | ||
| 13804 | "<ulink url='&YOCTO_DOCS_REF_URL;#resources-bugtracker'>Yocto Project Bugzilla</ulink>" | ||
| 13805 | section in the Yocto Project Reference Manual. | ||
| 13806 | For more detail on any of the following steps, see the Yocto Project | ||
| 13807 | <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink>. | ||
| 13808 | </para> | ||
| 13809 | |||
| 13810 | <para> | ||
| 13811 | Use the following general steps to submit a bug" | ||
| 13812 | |||
| 13813 | <orderedlist> | ||
| 13814 | <listitem><para> | ||
| 13815 | Open the Yocto Project implementation of | ||
| 13816 | <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>. | ||
| 13817 | </para></listitem> | ||
| 13818 | <listitem><para> | ||
| 13819 | Click "File a Bug" to enter a new bug. | ||
| 13820 | </para></listitem> | ||
| 13821 | <listitem><para> | ||
| 13822 | Choose the appropriate "Classification", "Product", and | ||
| 13823 | "Component" for which the bug was found. | ||
| 13824 | Bugs for the Yocto Project fall into one of several | ||
| 13825 | classifications, which in turn break down into several | ||
| 13826 | products and components. | ||
| 13827 | For example, for a bug against the | ||
| 13828 | <filename>meta-intel</filename> layer, you would choose | ||
| 13829 | "Build System, Metadata & Runtime", "BSPs", and | ||
| 13830 | "bsps-meta-intel", respectively. | ||
| 13831 | </para></listitem> | ||
| 13832 | <listitem><para> | ||
| 13833 | Choose the "Version" of the Yocto Project for which you found | ||
| 13834 | the bug (e.g. &DISTRO;). | ||
| 13835 | </para></listitem> | ||
| 13836 | <listitem><para> | ||
| 13837 | Determine and select the "Severity" of the bug. | ||
| 13838 | The severity indicates how the bug impacted your work. | ||
| 13839 | </para></listitem> | ||
| 13840 | <listitem><para> | ||
| 13841 | Choose the "Hardware" that the bug impacts. | ||
| 13842 | </para></listitem> | ||
| 13843 | <listitem><para> | ||
| 13844 | Choose the "Architecture" that the bug impacts. | ||
| 13845 | </para></listitem> | ||
| 13846 | <listitem><para> | ||
| 13847 | Choose a "Documentation change" item for the bug. | ||
| 13848 | Fixing a bug might or might not affect the Yocto Project | ||
| 13849 | documentation. | ||
| 13850 | If you are unsure of the impact to the documentation, select | ||
| 13851 | "Don't Know". | ||
| 13852 | </para></listitem> | ||
| 13853 | <listitem><para> | ||
| 13854 | Provide a brief "Summary" of the bug. | ||
| 13855 | Try to limit your summary to just a line or two and be sure | ||
| 13856 | to capture the essence of the bug. | ||
| 13857 | </para></listitem> | ||
| 13858 | <listitem><para> | ||
| 13859 | Provide a detailed "Description" of the bug. | ||
| 13860 | You should provide as much detail as you can about the context, | ||
| 13861 | behavior, output, and so forth that surrounds the bug. | ||
| 13862 | You can even attach supporting files for output from logs by | ||
| 13863 | using the "Add an attachment" button. | ||
| 13864 | </para></listitem> | ||
| 13865 | <listitem><para> | ||
| 13866 | Click the "Submit Bug" button submit the bug. | ||
| 13867 | A new Bugzilla number is assigned to the bug and the defect | ||
| 13868 | is logged in the bug tracking system. | ||
| 13869 | </para></listitem> | ||
| 13870 | </orderedlist> | ||
| 13871 | Once you file a bug, the bug is processed by the Yocto Project Bug | ||
| 13872 | Triage Team and further details concerning the bug are assigned | ||
| 13873 | (e.g. priority and owner). | ||
| 13874 | You are the "Submitter" of the bug and any further categorization, | ||
| 13875 | progress, or comments on the bug result in Bugzilla sending you an | ||
| 13876 | automated email concerning the particular change or progress to the | ||
| 13877 | bug. | ||
| 13878 | </para> | ||
| 13879 | </section> | ||
| 13880 | |||
| 13881 | <section id='how-to-submit-a-change'> | ||
| 13882 | <title>Submitting a Change to the Yocto Project</title> | ||
| 13883 | |||
| 13884 | <para> | ||
| 13885 | Contributions to the Yocto Project and OpenEmbedded are very welcome. | ||
| 13886 | Because the system is extremely configurable and flexible, we recognize | ||
| 13887 | that developers will want to extend, configure or optimize it for | ||
| 13888 | their specific uses. | ||
| 13889 | </para> | ||
| 13890 | |||
| 13891 | <para> | ||
| 13892 | The Yocto Project uses a mailing list and a patch-based workflow | ||
| 13893 | that is similar to the Linux kernel but contains important | ||
| 13894 | differences. | ||
| 13895 | In general, a mailing list exists through which you can submit | ||
| 13896 | patches. | ||
| 13897 | You should send patches to the appropriate mailing list so that they | ||
| 13898 | can be reviewed and merged by the appropriate maintainer. | ||
| 13899 | The specific mailing list you need to use depends on the | ||
| 13900 | location of the code you are changing. | ||
| 13901 | Each component (e.g. layer) should have a | ||
| 13902 | <filename>README</filename> file that indicates where to send | ||
| 13903 | the changes and which process to follow. | ||
| 13904 | </para> | ||
| 13905 | |||
| 13906 | <para> | ||
| 13907 | You can send the patch to the mailing list using whichever approach | ||
| 13908 | you feel comfortable with to generate the patch. | ||
| 13909 | Once sent, the patch is usually reviewed by the community at large. | ||
| 13910 | If somebody has concerns with the patch, they will usually voice | ||
| 13911 | their concern over the mailing list. | ||
| 13912 | If a patch does not receive any negative reviews, the maintainer of | ||
| 13913 | the affected layer typically takes the patch, tests it, and then | ||
| 13914 | based on successful testing, merges the patch. | ||
| 13915 | </para> | ||
| 13916 | |||
| 13917 | <para id='figuring-out-the-mailing-list-to-use'> | ||
| 13918 | The "poky" repository, which is the Yocto Project's reference build | ||
| 13919 | environment, is a hybrid repository that contains several | ||
| 13920 | individual pieces (e.g. BitBake, Metadata, documentation, | ||
| 13921 | and so forth) built using the combo-layer tool. | ||
| 13922 | The upstream location used for submitting changes varies by | ||
| 13923 | component: | ||
| 13924 | <itemizedlist> | ||
| 13925 | <listitem><para> | ||
| 13926 | <emphasis>Core Metadata:</emphasis> | ||
| 13927 | Send your patch to the | ||
| 13928 | <ulink url='http://lists.openembedded.org/mailman/listinfo/openembedded-core'>openembedded-core</ulink> | ||
| 13929 | mailing list. For example, a change to anything under | ||
| 13930 | the <filename>meta</filename> or | ||
| 13931 | <filename>scripts</filename> directories should be sent | ||
| 13932 | to this mailing list. | ||
| 13933 | </para></listitem> | ||
| 13934 | <listitem><para> | ||
| 13935 | <emphasis>BitBake:</emphasis> | ||
| 13936 | For changes to BitBake (i.e. anything under the | ||
| 13937 | <filename>bitbake</filename> directory), send your patch | ||
| 13938 | to the | ||
| 13939 | <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'>bitbake-devel</ulink> | ||
| 13940 | mailing list. | ||
| 13941 | </para></listitem> | ||
| 13942 | <listitem><para> | ||
| 13943 | <emphasis>"meta-*" trees:</emphasis> | ||
| 13944 | These trees contain Metadata. | ||
| 13945 | Use the | ||
| 13946 | <ulink url='https://lists.yoctoproject.org/listinfo/poky'>poky</ulink> | ||
| 13947 | mailing list. | ||
| 13948 | </para></listitem> | ||
| 13949 | </itemizedlist> | ||
| 13950 | </para> | ||
| 13951 | |||
| 13952 | <para> | ||
| 13953 | For changes to other layers hosted in the Yocto Project source | ||
| 13954 | repositories (i.e. <filename>yoctoproject.org</filename>), tools, | ||
| 13955 | and the Yocto Project documentation, use the | ||
| 13956 | <ulink url='https://lists.yoctoproject.org/listinfo/yocto'>Yocto Project</ulink> | ||
| 13957 | general mailing list. | ||
| 13958 | <note> | ||
| 13959 | Sometimes a layer's documentation specifies to use a | ||
| 13960 | particular mailing list. | ||
| 13961 | If so, use that list. | ||
| 13962 | </note> | ||
| 13963 | For additional recipes that do not fit into the core Metadata, you | ||
| 13964 | should determine which layer the recipe should go into and submit | ||
| 13965 | the change in the manner recommended by the documentation (e.g. | ||
| 13966 | the <filename>README</filename> file) supplied with the layer. | ||
| 13967 | If in doubt, please ask on the Yocto general mailing list or on | ||
| 13968 | the openembedded-devel mailing list. | ||
| 13969 | </para> | ||
| 13970 | |||
| 13971 | <para> | ||
| 13972 | You can also push a change upstream and request a maintainer to | ||
| 13973 | pull the change into the component's upstream repository. | ||
| 13974 | You do this by pushing to a contribution repository that is upstream. | ||
| 13975 | See the | ||
| 13976 | "<ulink url='&YOCTO_DOCS_OM_URL;#gs-git-workflows-and-the-yocto-project'>Git Workflows and the Yocto Project</ulink>" | ||
| 13977 | section in the Yocto Project Overview and Concepts Manual for additional | ||
| 13978 | concepts on working in the Yocto Project development environment. | ||
| 13979 | </para> | ||
| 13980 | |||
| 13981 | <para> | ||
| 13982 | Two commonly used testing repositories exist for | ||
| 13983 | OpenEmbedded-Core: | ||
| 13984 | <itemizedlist> | ||
| 13985 | <listitem><para> | ||
| 13986 | <emphasis>"ross/mut" branch:</emphasis> | ||
| 13987 | The "mut" (master-under-test) tree | ||
| 13988 | exists in the <filename>poky-contrib</filename> repository | ||
| 13989 | in the | ||
| 13990 | <ulink url='&YOCTO_GIT_URL;'>Yocto Project source repositories</ulink>. | ||
| 13991 | </para></listitem> | ||
| 13992 | <listitem><para> | ||
| 13993 | <emphasis>"master-next" branch:</emphasis> | ||
| 13994 | This branch is part of the main | ||
| 13995 | "poky" repository in the Yocto Project source repositories. | ||
| 13996 | </para></listitem> | ||
| 13997 | </itemizedlist> | ||
| 13998 | Maintainers use these branches to test submissions prior to merging | ||
| 13999 | patches. | ||
| 14000 | Thus, you can get an idea of the status of a patch based on | ||
| 14001 | whether the patch has been merged into one of these branches. | ||
| 14002 | <note> | ||
| 14003 | This system is imperfect and changes can sometimes get lost in the | ||
| 14004 | flow. | ||
| 14005 | Asking about the status of a patch or change is reasonable if the | ||
| 14006 | change has been idle for a while with no feedback. | ||
| 14007 | The Yocto Project does have plans to use | ||
| 14008 | <ulink url='https://en.wikipedia.org/wiki/Patchwork_(software)'>Patchwork</ulink> | ||
| 14009 | to track the status of patches and also to automatically preview | ||
| 14010 | patches. | ||
| 14011 | </note> | ||
| 14012 | </para> | ||
| 14013 | |||
| 14014 | <para> | ||
| 14015 | The following sections provide procedures for submitting a change. | ||
| 14016 | </para> | ||
| 14017 | |||
| 14018 | <section id='pushing-a-change-upstream'> | ||
| 14019 | <title>Using Scripts to Push a Change Upstream and Request a Pull</title> | ||
| 14020 | |||
| 14021 | <para> | ||
| 14022 | Follow this procedure to push a change to an upstream "contrib" | ||
| 14023 | Git repository: | ||
| 14024 | <note> | ||
| 14025 | You can find general Git information on how to push a change | ||
| 14026 | upstream in the | ||
| 14027 | <ulink url='http://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows'>Git Community Book</ulink>. | ||
| 14028 | </note> | ||
| 14029 | <orderedlist> | ||
| 14030 | <listitem><para> | ||
| 14031 | <emphasis>Make Your Changes Locally:</emphasis> | ||
| 14032 | Make your changes in your local Git repository. | ||
| 14033 | You should make small, controlled, isolated changes. | ||
| 14034 | Keeping changes small and isolated aids review, | ||
| 14035 | makes merging/rebasing easier and keeps the change | ||
| 14036 | history clean should anyone need to refer to it in | ||
| 14037 | future. | ||
| 14038 | </para></listitem> | ||
| 14039 | <listitem><para> | ||
| 14040 | <emphasis>Stage Your Changes:</emphasis> | ||
| 14041 | Stage your changes by using the <filename>git add</filename> | ||
| 14042 | command on each file you changed. | ||
| 14043 | </para></listitem> | ||
| 14044 | <listitem><para id='making-sure-you-have-correct-commit-information'> | ||
| 14045 | <emphasis>Commit Your Changes:</emphasis> | ||
| 14046 | Commit the change by using the | ||
| 14047 | <filename>git commit</filename> command. | ||
| 14048 | Make sure your commit information follows standards by | ||
| 14049 | following these accepted conventions: | ||
| 14050 | <itemizedlist> | ||
| 14051 | <listitem><para> | ||
| 14052 | Be sure to include a "Signed-off-by:" line in the | ||
| 14053 | same style as required by the Linux kernel. | ||
| 14054 | Adding this line signifies that you, the submitter, | ||
| 14055 | have agreed to the Developer's Certificate of | ||
| 14056 | Origin 1.1 as follows: | ||
| 14057 | <literallayout class='monospaced'> | ||
| 14058 | Developer's Certificate of Origin 1.1 | ||
| 14059 | |||
| 14060 | By making a contribution to this project, I certify that: | ||
| 14061 | |||
| 14062 | (a) The contribution was created in whole or in part by me and I | ||
| 14063 | have the right to submit it under the open source license | ||
| 14064 | indicated in the file; or | ||
| 14065 | |||
| 14066 | (b) The contribution is based upon previous work that, to the best | ||
| 14067 | of my knowledge, is covered under an appropriate open source | ||
| 14068 | license and I have the right under that license to submit that | ||
| 14069 | work with modifications, whether created in whole or in part | ||
| 14070 | by me, under the same open source license (unless I am | ||
| 14071 | permitted to submit under a different license), as indicated | ||
| 14072 | in the file; or | ||
| 14073 | |||
| 14074 | (c) The contribution was provided directly to me by some other | ||
| 14075 | person who certified (a), (b) or (c) and I have not modified | ||
| 14076 | it. | ||
| 14077 | |||
| 14078 | (d) I understand and agree that this project and the contribution | ||
| 14079 | are public and that a record of the contribution (including all | ||
| 14080 | personal information I submit with it, including my sign-off) is | ||
| 14081 | maintained indefinitely and may be redistributed consistent with | ||
| 14082 | this project or the open source license(s) involved. | ||
| 14083 | </literallayout> | ||
| 14084 | </para></listitem> | ||
| 14085 | <listitem><para> | ||
| 14086 | Provide a single-line summary of the change. | ||
| 14087 | and, | ||
| 14088 | if more explanation is needed, provide more | ||
| 14089 | detail in the body of the commit. | ||
| 14090 | This summary is typically viewable in the | ||
| 14091 | "shortlist" of changes. | ||
| 14092 | Thus, providing something short and descriptive | ||
| 14093 | that gives the reader a summary of the change is | ||
| 14094 | useful when viewing a list of many commits. | ||
| 14095 | You should prefix this short description with the | ||
| 14096 | recipe name (if changing a recipe), or else with | ||
| 14097 | the short form path to the file being changed. | ||
| 14098 | </para></listitem> | ||
| 14099 | <listitem><para> | ||
| 14100 | For the body of the commit message, provide | ||
| 14101 | detailed information that describes what you | ||
| 14102 | changed, why you made the change, and the approach | ||
| 14103 | you used. | ||
| 14104 | It might also be helpful if you mention how you | ||
| 14105 | tested the change. | ||
| 14106 | Provide as much detail as you can in the body of | ||
| 14107 | the commit message. | ||
| 14108 | <note> | ||
| 14109 | You do not need to provide a more detailed | ||
| 14110 | explanation of a change if the change is | ||
| 14111 | minor to the point of the single line | ||
| 14112 | summary providing all the information. | ||
| 14113 | </note> | ||
| 14114 | </para></listitem> | ||
| 14115 | <listitem><para> | ||
| 14116 | If the change addresses a specific bug or issue | ||
| 14117 | that is associated with a bug-tracking ID, | ||
| 14118 | include a reference to that ID in your detailed | ||
| 14119 | description. | ||
| 14120 | For example, the Yocto Project uses a specific | ||
| 14121 | convention for bug references - any commit that | ||
| 14122 | addresses a specific bug should use the following | ||
| 14123 | form for the detailed description. | ||
| 14124 | Be sure to use the actual bug-tracking ID from | ||
| 14125 | Bugzilla for | ||
| 14126 | <replaceable>bug-id</replaceable>: | ||
| 14127 | <literallayout class='monospaced'> | ||
| 14128 | Fixes [YOCTO #<replaceable>bug-id</replaceable>] | ||
| 14129 | |||
| 14130 | <replaceable>detailed description of change</replaceable> | ||
| 14131 | </literallayout> | ||
| 14132 | </para></listitem> | ||
| 14133 | </itemizedlist> | ||
| 14134 | </para></listitem> | ||
| 14135 | <listitem><para> | ||
| 14136 | <emphasis>Push Your Commits to a "Contrib" Upstream:</emphasis> | ||
| 14137 | If you have arranged for permissions to push to an | ||
| 14138 | upstream contrib repository, push the change to that | ||
| 14139 | repository: | ||
| 14140 | <literallayout class='monospaced'> | ||
| 14141 | $ git push <replaceable>upstream_remote_repo</replaceable> <replaceable>local_branch_name</replaceable> | ||
| 14142 | </literallayout> | ||
| 14143 | For example, suppose you have permissions to push into the | ||
| 14144 | upstream <filename>meta-intel-contrib</filename> | ||
| 14145 | repository and you are working in a local branch named | ||
| 14146 | <replaceable>your_name</replaceable><filename>/README</filename>. | ||
| 14147 | The following command pushes your local commits to the | ||
| 14148 | <filename>meta-intel-contrib</filename> upstream | ||
| 14149 | repository and puts the commit in a branch named | ||
| 14150 | <replaceable>your_name</replaceable><filename>/README</filename>: | ||
| 14151 | <literallayout class='monospaced'> | ||
| 14152 | $ git push meta-intel-contrib <replaceable>your_name</replaceable>/README | ||
| 14153 | </literallayout> | ||
| 14154 | </para></listitem> | ||
| 14155 | <listitem><para id='push-determine-who-to-notify'> | ||
| 14156 | <emphasis>Determine Who to Notify:</emphasis> | ||
| 14157 | Determine the maintainer or the mailing list | ||
| 14158 | that you need to notify for the change.</para> | ||
| 14159 | |||
| 14160 | <para>Before submitting any change, you need to be sure | ||
| 14161 | who the maintainer is or what mailing list that you need | ||
| 14162 | to notify. | ||
| 14163 | Use either these methods to find out: | ||
| 14164 | <itemizedlist> | ||
| 14165 | <listitem><para> | ||
| 14166 | <emphasis>Maintenance File:</emphasis> | ||
| 14167 | Examine the <filename>maintainers.inc</filename> | ||
| 14168 | file, which is located in the | ||
| 14169 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> | ||
| 14170 | at | ||
| 14171 | <filename>meta/conf/distro/include</filename>, | ||
| 14172 | to see who is responsible for code. | ||
| 14173 | </para></listitem> | ||
| 14174 | <listitem><para> | ||
| 14175 | <emphasis>Search by File:</emphasis> | ||
| 14176 | Using <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>, | ||
| 14177 | you can enter the following command to bring up a | ||
| 14178 | short list of all commits against a specific file: | ||
| 14179 | <literallayout class='monospaced'> | ||
| 14180 | git shortlog -- <replaceable>filename</replaceable> | ||
| 14181 | </literallayout> | ||
| 14182 | Just provide the name of the file for which you | ||
| 14183 | are interested. | ||
| 14184 | The information returned is not ordered by history | ||
| 14185 | but does include a list of everyone who has | ||
| 14186 | committed grouped by name. | ||
| 14187 | From the list, you can see who is responsible for | ||
| 14188 | the bulk of the changes against the file. | ||
| 14189 | </para></listitem> | ||
| 14190 | <listitem><para> | ||
| 14191 | <emphasis>Examine the List of Mailing Lists:</emphasis> | ||
| 14192 | For a list of the Yocto Project and related mailing | ||
| 14193 | lists, see the | ||
| 14194 | "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" | ||
| 14195 | section in the Yocto Project Reference Manual. | ||
| 14196 | </para></listitem> | ||
| 14197 | </itemizedlist> | ||
| 14198 | </para></listitem> | ||
| 14199 | <listitem><para> | ||
| 14200 | <emphasis>Make a Pull Request:</emphasis> | ||
| 14201 | Notify the maintainer or the mailing list that you have | ||
| 14202 | pushed a change by making a pull request.</para> | ||
| 14203 | |||
| 14204 | <para>The Yocto Project provides two scripts that | ||
| 14205 | conveniently let you generate and send pull requests to the | ||
| 14206 | Yocto Project. | ||
| 14207 | These scripts are <filename>create-pull-request</filename> | ||
| 14208 | and <filename>send-pull-request</filename>. | ||
| 14209 | You can find these scripts in the | ||
| 14210 | <filename>scripts</filename> directory within the | ||
| 14211 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> | ||
| 14212 | (e.g. <filename>~/poky/scripts</filename>). | ||
| 14213 | </para> | ||
| 14214 | |||
| 14215 | <para>Using these scripts correctly formats the requests | ||
| 14216 | without introducing any whitespace or HTML formatting. | ||
| 14217 | The maintainer that receives your patches either directly | ||
| 14218 | or through the mailing list needs to be able to save and | ||
| 14219 | apply them directly from your emails. | ||
| 14220 | Using these scripts is the preferred method for sending | ||
| 14221 | patches.</para> | ||
| 14222 | |||
| 14223 | <para>First, create the pull request. | ||
| 14224 | For example, the following command runs the script, | ||
| 14225 | specifies the upstream repository in the contrib directory | ||
| 14226 | into which you pushed the change, and provides a subject | ||
| 14227 | line in the created patch files: | ||
| 14228 | <literallayout class='monospaced'> | ||
| 14229 | $ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README" | ||
| 14230 | </literallayout> | ||
| 14231 | Running this script forms | ||
| 14232 | <filename>*.patch</filename> files in a folder named | ||
| 14233 | <filename>pull-</filename><replaceable>PID</replaceable> | ||
| 14234 | in the current directory. | ||
| 14235 | One of the patch files is a cover letter.</para> | ||
| 14236 | |||
| 14237 | <para>Before running the | ||
| 14238 | <filename>send-pull-request</filename> script, you must | ||
| 14239 | edit the cover letter patch to insert information about | ||
| 14240 | your change. | ||
| 14241 | After editing the cover letter, send the pull request. | ||
| 14242 | For example, the following command runs the script and | ||
| 14243 | specifies the patch directory and email address. | ||
| 14244 | In this example, the email address is a mailing list: | ||
| 14245 | <literallayout class='monospaced'> | ||
| 14246 | $ ~/poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org | ||
| 14247 | </literallayout> | ||
| 14248 | You need to follow the prompts as the script is | ||
| 14249 | interactive. | ||
| 14250 | <note> | ||
| 14251 | For help on using these scripts, simply provide the | ||
| 14252 | <filename>-h</filename> argument as follows: | ||
| 14253 | <literallayout class='monospaced'> | ||
| 14254 | $ poky/scripts/create-pull-request -h | ||
| 14255 | $ poky/scripts/send-pull-request -h | ||
| 14256 | </literallayout> | ||
| 14257 | </note> | ||
| 14258 | </para></listitem> | ||
| 14259 | </orderedlist> | ||
| 14260 | </para> | ||
| 14261 | </section> | ||
| 14262 | |||
| 14263 | <section id='submitting-a-patch'> | ||
| 14264 | <title>Using Email to Submit a Patch</title> | ||
| 14265 | |||
| 14266 | <para> | ||
| 14267 | You can submit patches without using the | ||
| 14268 | <filename>create-pull-request</filename> and | ||
| 14269 | <filename>send-pull-request</filename> scripts described in the | ||
| 14270 | previous section. | ||
| 14271 | However, keep in mind, the preferred method is to use the scripts. | ||
| 14272 | </para> | ||
| 14273 | |||
| 14274 | <para> | ||
| 14275 | Depending on the components changed, you need to submit the email | ||
| 14276 | to a specific mailing list. | ||
| 14277 | For some guidance on which mailing list to use, see the | ||
| 14278 | <link linkend='figuring-out-the-mailing-list-to-use'>list</link> | ||
| 14279 | at the beginning of this section. | ||
| 14280 | For a description of all the available mailing lists, see the | ||
| 14281 | "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>" | ||
| 14282 | section in the Yocto Project Reference Manual. | ||
| 14283 | </para> | ||
| 14284 | |||
| 14285 | <para> | ||
| 14286 | Here is the general procedure on how to submit a patch through | ||
| 14287 | email without using the scripts: | ||
| 14288 | <orderedlist> | ||
| 14289 | <listitem><para> | ||
| 14290 | <emphasis>Make Your Changes Locally:</emphasis> | ||
| 14291 | Make your changes in your local Git repository. | ||
| 14292 | You should make small, controlled, isolated changes. | ||
| 14293 | Keeping changes small and isolated aids review, | ||
| 14294 | makes merging/rebasing easier and keeps the change | ||
| 14295 | history clean should anyone need to refer to it in | ||
| 14296 | future. | ||
| 14297 | </para></listitem> | ||
| 14298 | <listitem><para> | ||
| 14299 | <emphasis>Stage Your Changes:</emphasis> | ||
| 14300 | Stage your changes by using the <filename>git add</filename> | ||
| 14301 | command on each file you changed. | ||
| 14302 | </para></listitem> | ||
| 14303 | <listitem><para> | ||
| 14304 | <emphasis>Commit Your Changes:</emphasis> | ||
| 14305 | Commit the change by using the | ||
| 14306 | <filename>git commit --signoff</filename> command. | ||
| 14307 | Using the <filename>--signoff</filename> option identifies | ||
| 14308 | you as the person making the change and also satisfies | ||
| 14309 | the Developer's Certificate of Origin (DCO) shown earlier. | ||
| 14310 | </para> | ||
| 14311 | |||
| 14312 | <para>When you form a commit, you must follow certain | ||
| 14313 | standards established by the Yocto Project development | ||
| 14314 | team. | ||
| 14315 | See | ||
| 14316 | <link linkend='making-sure-you-have-correct-commit-information'>Step 3</link> | ||
| 14317 | in the previous section for information on how to | ||
| 14318 | provide commit information that meets Yocto Project | ||
| 14319 | commit message standards. | ||
| 14320 | </para></listitem> | ||
| 14321 | <listitem><para> | ||
| 14322 | <emphasis>Format the Commit:</emphasis> | ||
| 14323 | Format the commit into an email message. | ||
| 14324 | To format commits, use the | ||
| 14325 | <filename>git format-patch</filename> command. | ||
| 14326 | When you provide the command, you must include a revision | ||
| 14327 | list or a number of patches as part of the command. | ||
| 14328 | For example, either of these two commands takes your most | ||
| 14329 | recent single commit and formats it as an email message in | ||
| 14330 | the current directory: | ||
| 14331 | <literallayout class='monospaced'> | ||
| 14332 | $ git format-patch -1 | ||
| 14333 | </literallayout> | ||
| 14334 | or | ||
| 14335 | <literallayout class='monospaced'> | ||
| 14336 | $ git format-patch HEAD~ | ||
| 14337 | </literallayout></para> | ||
| 14338 | |||
| 14339 | <para>After the command is run, the current directory | ||
| 14340 | contains a numbered <filename>.patch</filename> file for | ||
| 14341 | the commit.</para> | ||
| 14342 | |||
| 14343 | <para>If you provide several commits as part of the | ||
| 14344 | command, the <filename>git format-patch</filename> command | ||
| 14345 | produces a series of numbered files in the current | ||
| 14346 | directory – one for each commit. | ||
| 14347 | If you have more than one patch, you should also use the | ||
| 14348 | <filename>--cover</filename> option with the command, | ||
| 14349 | which generates a cover letter as the first "patch" in | ||
| 14350 | the series. | ||
| 14351 | You can then edit the cover letter to provide a | ||
| 14352 | description for the series of patches. | ||
| 14353 | For information on the | ||
| 14354 | <filename>git format-patch</filename> command, | ||
| 14355 | see <filename>GIT_FORMAT_PATCH(1)</filename> displayed | ||
| 14356 | using the <filename>man git-format-patch</filename> | ||
| 14357 | command. | ||
| 14358 | <note> | ||
| 14359 | If you are or will be a frequent contributor to the | ||
| 14360 | Yocto Project or to OpenEmbedded, you might consider | ||
| 14361 | requesting a contrib area and the necessary associated | ||
| 14362 | rights. | ||
| 14363 | </note> | ||
| 14364 | </para></listitem> | ||
| 14365 | <listitem><para> | ||
| 14366 | <emphasis>Import the Files Into Your Mail Client:</emphasis> | ||
| 14367 | Import the files into your mail client by using the | ||
| 14368 | <filename>git send-email</filename> command. | ||
| 14369 | <note> | ||
| 14370 | In order to use <filename>git send-email</filename>, | ||
| 14371 | you must have the proper Git packages installed on | ||
| 14372 | your host. | ||
| 14373 | For Ubuntu, Debian, and Fedora the package is | ||
| 14374 | <filename>git-email</filename>. | ||
| 14375 | </note></para> | ||
| 14376 | |||
| 14377 | <para>The <filename>git send-email</filename> command | ||
| 14378 | sends email by using a local or remote Mail Transport Agent | ||
| 14379 | (MTA) such as <filename>msmtp</filename>, | ||
| 14380 | <filename>sendmail</filename>, or through a direct | ||
| 14381 | <filename>smtp</filename> configuration in your Git | ||
| 14382 | <filename>~/.gitconfig</filename> file. | ||
| 14383 | If you are submitting patches through email only, it is | ||
| 14384 | very important that you submit them without any whitespace | ||
| 14385 | or HTML formatting that either you or your mailer | ||
| 14386 | introduces. | ||
| 14387 | The maintainer that receives your patches needs to be able | ||
| 14388 | to save and apply them directly from your emails. | ||
| 14389 | A good way to verify that what you are sending will be | ||
| 14390 | applicable by the maintainer is to do a dry run and send | ||
| 14391 | them to yourself and then save and apply them as the | ||
| 14392 | maintainer would.</para> | ||
| 14393 | |||
| 14394 | <para>The <filename>git send-email</filename> command is | ||
| 14395 | the preferred method for sending your patches using | ||
| 14396 | email since there is no risk of compromising whitespace | ||
| 14397 | in the body of the message, which can occur when you use | ||
| 14398 | your own mail client. | ||
| 14399 | The command also has several options that let you | ||
| 14400 | specify recipients and perform further editing of the | ||
| 14401 | email message. | ||
| 14402 | For information on how to use the | ||
| 14403 | <filename>git send-email</filename> command, | ||
| 14404 | see <filename>GIT-SEND-EMAIL(1)</filename> displayed using | ||
| 14405 | the <filename>man git-send-email</filename> command. | ||
| 14406 | </para></listitem> | ||
| 14407 | </orderedlist> | ||
| 14408 | </para> | ||
| 14409 | </section> | ||
| 14410 | </section> | ||
| 14411 | </section> | ||
| 14412 | |||
| 13786 | <section id='working-with-licenses'> | 14413 | <section id='working-with-licenses'> |
| 13787 | <title>Working With Licenses</title> | 14414 | <title>Working With Licenses</title> |
| 13788 | 14415 | ||