diff options
Diffstat (limited to 'documentation/dev-manual/dev-manual-newbie.xml')
-rw-r--r-- | documentation/dev-manual/dev-manual-newbie.xml | 119 |
1 files changed, 59 insertions, 60 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml index 94f3471f13..a67a173810 100644 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ b/documentation/dev-manual/dev-manual-newbie.xml @@ -874,54 +874,53 @@ <listitem><para>Submit the bug by clicking the "Submit Bug" button.</para></listitem> </orderedlist> </para> - - <note> - Bugs in the Yocto Project Bugzilla follow naming convention: - <filename>[YOCTO #<number>]</filename>, where <filename><number></filename> is the - assigned defect ID used in Bugzilla. - So, for example, a valid way to refer to a defect would be <filename>[YOCTO #1011]</filename>. - This convention becomes important if you are submitting patches against the Yocto Project - code itself. - </note> </section> <section id='how-to-submit-a-change'> <title>How to Submit a Change</title> <para> - Contributions to the Yocto Project are very welcome. - Because the Yocto Project is extremely configurable and flexible, we recognize that developers + Contributions to the Yocto Project and OpenEmbedded are very welcome. + Because the system is extremely configurable and flexible, we recognize that developers will want to extend, configure or optimize it for their specific uses. - You should send patches to the appropriate Yocto Project mailing list to get them - in front of the Yocto Project Maintainer. - For a list of the Yocto Project mailing lists, see the + You should send patches to the appropriate mailing list so that they + can be reviewed and merged by the appropriate maintainer. + 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 following is some guidance on which mailing list to use for what type of defect: + The following is some guidance on which mailing list to use for what type of change: <itemizedlist> - <listitem><para>For defects against the Yocto Project build system Poky, send - your patch to the - <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> mailing list. - This mailing list corresponds to issues that are not specific to the Yocto Project but - are part of the OE-core. - For example, a defect against anything in the <filename>meta</filename> layer - or the BitBake Manual could be sent to this mailing list.</para></listitem> - <listitem><para>For defects against Yocto-specific layers, tools, and Yocto Project - documentation use the - <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> mailing list. - This mailing list corresponds to Yocto-specific areas such as - <filename>meta-yocto</filename>, <filename>meta-intel</filename>, - <filename>linux-yocto</filename>, and <filename>documentation</filename>.</para></listitem> + <listitem><para>For changes to the core metadata, 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-yocto</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 yoctoproject.org (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> 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 the developer has agreed to the Developer's Certificate of Origin 1.1 + 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 @@ -950,52 +949,52 @@ maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. </literallayout> - A Poky contributions tree (<filename>poky-contrib</filename>, - <filename>git://git.yoctoproject.org/poky-contrib.git</filename>) - exists for contributors to stage contributions. - If people desire such access, please ask on the mailing list. - Usually, the Yocto Project team will grant access to anyone with a proven track - record of good patches. </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 to the - Yocto Project. - Keeping changes small and isolated lets you best keep pace with future Yocto Project changes. + 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> - When you create a commit, you must follow certain standards established by the - Yocto Project development team. - For each commit, you must provide a single-line summary of the change and you - almost always provide a more detailed description of what you did (i.e. the body - of the commit). + 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 description. - Here are the Yocto Project commit message guidelines: + 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 by source control systems. + 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 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. + 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, prefix your detailed description - with the bug or issue ID. - For example, the Yocto Project tracks bugs using a bug-naming convention. - Any commits that address a bug must start with the bug ID in the description - as follows: + 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 include the + bug ID in the description (typically at the end) as follows: <literallayout class='monospaced'> - YOCTO #<bug-id>: <Detailed description of commit> + <detailed description of change> + + [YOCTO #<bug-id>] </literallayout></para></listitem> + Where <bug-id> is replaced with the specific bug ID from the + Yocto Project Bugzilla instance. </itemizedlist> </para> @@ -1016,11 +1015,11 @@ The basic flow for pushing a change to an upstream "contrib" Git repository is as follows: <itemizedlist> <listitem><para>Make your changes in your local Git repository.</para></listitem> - <listitem><para>Stage your commit (or change) by using the <filename>git add</filename> - command.</para></listitem> + <listitem><para>Stage your changes by using the <filename>git add</filename> + command on each file you changed.</para></listitem> <listitem><para>Commit the change by using the <filename>git commit</filename> command and push it to the "contrib" repository. - Be sure to provide a commit message that follows the project’s commit standards + Be sure to provide a commit message that follows the project’s commit message standards as described earlier.</para></listitem> <listitem><para>Notify the maintainer that you have pushed a change by making a pull request. @@ -1031,10 +1030,10 @@ You can find these scripts in the <filename>scripts</filename> directory of the Yocto Project file structure.</para> <para>For help on using these scripts, simply provide the - <filename>--help</filename> argument as follows: + <filename>-h</filename> argument as follows: <literallayout class='monospaced'> - $ ~/poky/scripts/create-pull-request --help - $ ~/poky/scripts/send-pull-request --help + $ ~/poky/scripts/create-pull-request -h + $ ~/poky/scripts/send-pull-request -h </literallayout></para></listitem> </itemizedlist> </para> @@ -1054,8 +1053,8 @@ Here is a general procedure: <itemizedlist> <listitem><para>Make your changes in your local Git repository.</para></listitem> - <listitem><para>Stage your commit (or change) by using the <filename>git add</filename> - command.</para></listitem> + <listitem><para>Stage your changes by using the <filename>git add</filename> + command on each file you changed.</para></listitem> <listitem><para>Commit the change by using the <filename>git commit --signoff</filename> command. Using the <filename>--signoff</filename> option identifies you as the person |