diff options
Diffstat (limited to 'documentation')
| -rw-r--r-- | documentation/dev-manual/dev-manual-newbie.xml | 362 |
1 files changed, 234 insertions, 128 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml index 75c992f16b..4fd0d3a60c 100644 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ b/documentation/dev-manual/dev-manual-newbie.xml @@ -1394,83 +1394,182 @@ can be reviewed and merged by the appropriate maintainer. </para> - <para> - Before submitting any change, be sure to find out who you should be - notifying. - Several methods exist through which you find out who you should be copying - or notifying: - <itemizedlist> - <listitem><para><emphasis>Maintenance File:</emphasis> - Examine the <filename>maintainers.inc</filename> file, which is - located in the - <link linkend='source-directory'>Source Directory</link> - at <filename>meta-poky/conf/distro/include</filename>, to - see who is responsible for code. - </para></listitem> - <listitem><para><emphasis>Board Support Package (BSP) README Files:</emphasis> - For BSP maintainers of supported BSPs, you can examine - individual BSP <filename>README</filename> files. - In addition, some layers (such as the <filename>meta-intel</filename> layer), - include a <filename>MAINTAINERS</filename> file which contains - a list of all supported BSP maintainers for that layer. - </para></listitem> - <listitem><para><emphasis>Search by File:</emphasis> - Using <link linkend='git'>Git</link>, you can enter the - following command to bring up a short list of all commits - against a specific file: - <literallayout class='monospaced'> - git shortlog -- <replaceable>filename</replaceable> - </literallayout> - Just provide the name of the file for which you are interested. - The information returned is not ordered by history but does - include a list of all committers grouped by name. - From the list, you can see who is responsible for the bulk of - the changes against the file. - </para></listitem> - </itemizedlist> - </para> + <section id='submit-change-overview'> + <title>Overview</title> - <para> - For a list of the Yocto Project and related mailing lists, see the - "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in - the Yocto Project Reference Manual. - </para> + <para> + The Yocto Project uses a mailing list and patch-based workflow + that is similar to the Linux kernel but contains important + differences. + In general, a mailing list exists through which you can submit + patches. + The specific mailing list you need to use depends on the + location of the code you are changing. + Each component (e.g. layer) should have a + <filename>README</filename> file that indicates where to send + the changes and which process to follow. + </para> - <para> - Here is some guidance on which mailing list to use for what type of change: - <itemizedlist> - <listitem><para>For changes to the core - <link linkend='metadata'>Metadata</link>, send your patch to the - <ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'>openembedded-core</ulink> mailing list. - For example, a change to anything under the <filename>meta</filename> or - <filename>scripts</filename> directories - should be sent to this mailing list.</para></listitem> - <listitem><para>For changes to BitBake (anything under the <filename>bitbake</filename> - directory), send your patch to the - <ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem> - <listitem><para>For changes to <filename>meta-poky</filename>, send your patch to the - <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem> - <listitem><para>For changes to other layers hosted on - <filename>yoctoproject.org</filename> (unless the - layer's documentation specifies otherwise), tools, and Yocto Project - documentation, use the - <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> mailing list.</para></listitem> - <listitem><para>For additional recipes that do not fit into the core Metadata, - you should determine which layer the recipe should go into and submit the - change in the manner recommended by the documentation (e.g. README) supplied - with the layer. If in doubt, please ask on the - <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> or - <ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'>openembedded-devel</ulink> - mailing lists.</para></listitem> - </itemizedlist> - </para> + <para> + You can send the patch to the mailing list using whichever approach + you feel comfortable with to generate the patch. + Once sent, the patch is usually reviewed by the community at large. + If somebody has concerns with the patch, they will usually voice + their concern over the mailing list. + If a patch does not receive any negative reviews, the maintainer of + the affected layer typically takes the patch, tests it, and then + based on successful testing, merges the patch. + </para> - <para> - When you send a patch, be sure to include a "Signed-off-by:" - line in the same style as required by the Linux kernel. - Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1 - as follows: - <literallayout class='monospaced'> + <para> + Specific to OpenEmbedded-Core, two commonly used testing trees + exist: + <itemizedlist> + <listitem><para> + <emphasis>"ross/mut" branch:</emphasis> + The "mut" (master-under-test) tree + exists in the <filename>poky-contrib</filename> repository + in the + <ulink url='&YOCTO_GIT_URL;'>Yocto Project source repositories</ulink>. + </para></listitem> + <listitem><para> + <emphasis>"master-next" branch:</emphasis> + This branch is part of the main + "poky" repository in the Yocto Project source repositories. + </para></listitem> + </itemizedlist> + Maintainers use these branches to test submissions prior to merging + patches. + Thus, you can get an idea of the status of a patch based on + whether the patch has been merged into one of these branches. + </para> + + <para> + This system is imperfect and patches can sometimes get lost in the + flow. + Asking about the status of a patch is reasonable if the patch + has been idle for a while with no feedback. + The Yocto Project does have plans to use + <ulink url='https://en.wikipedia.org/wiki/Patchwork_(software)'>Patchwork</ulink> + to track the status of patches and also to automatically preview + patches. + </para> + + <para> + The following sections provide general instructions for both + pushing changes upstream and for submitting changes as patches. + </para> + </section> + + <section id='submit-change-submissions-to-poky'> + <title>Submissions to Poky</title> + + <para> + The "poky" repository, which is the Yocto Project's reference build + environment, is a hybrid repository that contains several + individual pieces (e.g. BitBake, OpenEmbedded-Core, meta-yocto, + documentation, and so forth) built using the combo-layer tool. + The upstream location used for submitting changes varies by + component: + <itemizedlist> + <listitem><para> + <emphasis>Core Metadata:</emphasis> + Send your patch to the + <ulink url='http://lists.openembedded.org/mailman/listinfo/openembedded-core'>openembedded-core</ulink> + mailing list. For example, a change to anything under + the <filename>meta</filename> or + <filename>scripts</filename> directories should be sent + to this mailing list. + </para></listitem> + <listitem><para> + <emphasis>BitBake:</emphasis> + For changes to BitBake (i.e. anything under the + <filename>bitbake</filename> directory), send your patch + to the + <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'>bitbake-devel</ulink> + mailing list. + </para></listitem> + <listitem><para> + <emphasis>"meta-yocto-bsp" and "meta-poky" trees:</emphasis> + These trees are + part of the "meta-yocto" repository in the Yocto Project + source repositories. + Use the + <ulink url='https://lists.yoctoproject.org/listinfo/poky'>poky</ulink> + mailing list. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='submit-change-submissions-to-other-layers'> + <title>Submissions to Other Layers</title> + + <para> + For changes to other layers hosted in the Yocto Project source + repositories (i.e. <filename>yoctoproject.org</filename>), tools, + and the Yocto Project documentation, use the + <ulink url='https://lists.yoctoproject.org/listinfo/yocto'>Yocto Project</ulink> + general mailing list. + <note> + Sometimes a layer's documentation specifies to use a + particular mailing list. + If so, use that list. + </note> + For additional recipes that do not fit into the core Metadata, you + should determine which layer the recipe should go into and submit + the change in the manner recommended by the documentation (e.g. + the <filename>README</filename> file) supplied with the layer. + If in doubt, please ask on the Yocto general mailing list or on + the openembedded-devel mailing list. + </para> + </section> + + <section id='submit-change-patch-submission-details'> + <title>Patch Submission Details</title> + + <para> + When submitting any change, you can check who you should be + notifying. + Use either of these methods to find out: + <itemizedlist> + <listitem><para> + <emphasis>Maintenance File:</emphasis> + Examine the <filename>maintainers.inc</filename> file, which is + located in the + <link linkend='source-directory'>Source Directory</link> + at <filename>meta-poky/conf/distro/include</filename>, to + see who is responsible for code. + </para></listitem> + <listitem><para> + <emphasis>Search by File:</emphasis> + Using <link linkend='git'>Git</link>, you can enter the + following command to bring up a short list of all commits + against a specific file: + <literallayout class='monospaced'> + git shortlog -- <replaceable>filename</replaceable> + </literallayout> + Just provide the name of the file for which you are interested. + The information returned is not ordered by history but does + include a list of all committers grouped by name. + From the list, you can see who is responsible for the bulk of + the changes against the file. + </para></listitem> + </itemizedlist> + </para> + + <para> + For a list of the Yocto Project and related mailing lists, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" + section in the Yocto Project Reference Manual. + </para> + + <para> + When you send a patch, be sure to include a "Signed-off-by:" + line in the same style as required by the Linux kernel. + Adding this line signifies that you, the submitter, have agreed + to the Developer's Certificate of Origin 1.1 as follows: + <literallayout class='monospaced'> Developer's Certificate of Origin 1.1 By making a contribution to this project, I certify that: @@ -1496,68 +1595,75 @@ personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. - </literallayout> - </para> + </literallayout> + </para> - <para> - In a collaborative environment, it is necessary to have some sort of standard - or method through which you submit changes. - Otherwise, things could get quite chaotic. - One general practice to follow is to make small, controlled changes. - Keeping changes small and isolated aids review, makes merging/rebasing easier - and keeps the change history clean when anyone needs to refer to it in future. - </para> + <para> + In a collaborative environment, it is necessary to have some sort + of standard or method through which you submit changes. + Otherwise, things could get quite chaotic. + One general practice to follow is to make small, controlled changes. + Keeping changes small and isolated aids review, makes + merging/rebasing easier and keeps the change history clean should + anyone need to refer to it in future. + </para> - <para> - When you make a commit, you must follow certain standards established by the - OpenEmbedded and Yocto Project development teams. - For each commit, you must provide a single-line summary of the change and you - should almost always provide a more detailed description of what you did (i.e. - the body of the commit message). - The only exceptions for not providing a detailed description would be if your - change is a simple, self-explanatory change that needs no further description - beyond the summary. - Here are the guidelines for composing a commit message: - <itemizedlist> - <listitem><para>Provide a single-line, short summary of the change. - This summary is typically viewable in the "shortlist" of changes. - Thus, providing something short and descriptive that gives the reader - a summary of the change is useful when viewing a list of many commits. - This short description should be prefixed by the recipe name (if changing a recipe), or - else the short form path to the file being changed. - </para></listitem> - <listitem><para>For the body of the commit message, provide detailed information - that describes what you changed, why you made the change, and the approach - you used. It may also be helpful if you mention how you tested the change. - Provide as much detail as you can in the body of the commit message. - </para></listitem> - <listitem><para> - If the change addresses a specific bug or issue that is - associated with a bug-tracking ID, include a reference to that - ID in your detailed description. - For example, the Yocto Project uses a specific convention for - bug references - any commit that addresses a specific bug should - use the following form for the detailed description: - <literallayout class='monospaced'> + <para> + When you make a commit, you must follow certain standards + established by the OpenEmbedded and Yocto Project development teams. + For each commit, you must provide a single-line summary of the + change and you should almost always provide a more detailed + description of what you did (i.e. the body of the commit message). + The only exceptions for not providing a detailed description would + be if your change is a simple, self-explanatory change that needs + no further description beyond the summary. + Here are the guidelines for composing a commit message: + <itemizedlist> + <listitem><para> + Provide a single-line, short summary of the change. + This summary is typically viewable in the "shortlist" of + changes. + Thus, providing something short and descriptive that + gives the reader a summary of the change is useful when + viewing a list of many commits. + You should prefix this short description with the recipe + name (if changing a recipe), or else with the short form + path to the file being changed. + </para></listitem> + <listitem><para> + For the body of the commit message, provide detailed + information that describes what you changed, why you made + the change, and the approach you used. + It might also be helpful if you mention how you tested + the change. + Provide as much detail as you can in the body of the + commit message. + </para></listitem> + <listitem><para> + If the change addresses a specific bug or issue that is + associated with a bug-tracking ID, include a reference + to that ID in your detailed description. + For example, the Yocto Project uses a specific convention + for bug references - any commit that addresses a specific + bug should use the following form for the detailed + description: + <literallayout class='monospaced'> Fixes [YOCTO #<replaceable>bug-id</replaceable>] <replaceable>detailed description of change</replaceable> - </literallayout></para></listitem> + </literallayout> + </para></listitem> Where <replaceable>bug-id</replaceable> is replaced with the specific bug ID from the Yocto Project Bugzilla instance. - </itemizedlist> - </para> - - <para> - You can find more guidance on creating well-formed commit messages at this OpenEmbedded - wiki page: - <ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>. - </para> + </itemizedlist> + </para> - <para> - The next two sections describe general instructions for both pushing - changes upstream and for submitting changes as patches. - </para> + <para> + You can find more guidance on creating well-formed commit messages + at this OpenEmbedded wiki page: + <ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>. + </para> + </section> <section id='pushing-a-change-upstream'> <title>Using Scripts to Push a Change Upstream and Request a Pull</title> |