From 257e61a2cb85cb849f18e9d2f314cab467be3c80 Mon Sep 17 00:00:00 2001 From: Paul Eggleton Date: Mon, 2 Jul 2012 10:20:20 +0100 Subject: dev-manual: tidy up "How to Submit a Change" section * Change some of the language and patch submission directions to correctly represent how we work together with OpenEmbedded (this changed with the introduction of OE-Core a few releases ago). * Correct --help option to -h for pull request scripts * Clarify commit message guidelines * Touch up a few other bits and pieces Fixes [YOCTO #2671]. (From yocto-docs rev: 3170ce5e0757951afee13207c117316e33449b39) Signed-off-by: Paul Eggleton Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-newbie.xml | 119 ++++++++++++------------- 1 file changed, 59 insertions(+), 60 deletions(-) (limited to 'documentation/dev-manual') 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 @@ Submit the bug by clicking the "Submit Bug" button. - - - Bugs in the Yocto Project Bugzilla follow naming convention: - [YOCTO #<number>], where <number> is the - assigned defect ID used in Bugzilla. - So, for example, a valid way to refer to a defect would be [YOCTO #1011]. - This convention becomes important if you are submitting patches against the Yocto Project - code itself. -
How to Submit a Change - 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 "Mailing lists" section in The Yocto Project Reference Manual. - 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: - For defects against the Yocto Project build system Poky, send - your patch to the - 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 meta layer - or the BitBake Manual could be sent to this mailing list. - For defects against Yocto-specific layers, tools, and Yocto Project - documentation use the - mailing list. - This mailing list corresponds to Yocto-specific areas such as - meta-yocto, meta-intel, - linux-yocto, and documentation. + For changes to the core metadata, send your patch to the + openembedded-core mailing list. + For example, a change to anything under the meta or + scripts directories + should be sent to this mailing list. + For changes to BitBake (anything under the bitbake + directory), send your patch to the + bitbake-devel mailing list. + For changes to meta-yocto, send your patch to the + poky mailing list. + For changes to other layers hosted on yoctoproject.org (unless the + layer's documentation specifies otherwise), tools, and Yocto Project + documentation, use the + yocto mailing list. + 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 + yocto or + openembedded-devel + mailing lists. 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: 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. - A Poky contributions tree (poky-contrib, - git://git.yoctoproject.org/poky-contrib.git) - 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. 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. - 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: 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. 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. 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: - YOCTO #<bug-id>: <Detailed description of commit> + <detailed description of change> + + [YOCTO #<bug-id>] + Where <bug-id> is replaced with the specific bug ID from the + Yocto Project Bugzilla instance. @@ -1016,11 +1015,11 @@ The basic flow for pushing a change to an upstream "contrib" Git repository is as follows: Make your changes in your local Git repository. - Stage your commit (or change) by using the git add - command. + Stage your changes by using the git add + command on each file you changed. Commit the change by using the git commit 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. 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 scripts directory of the Yocto Project file structure. For help on using these scripts, simply provide the - --help argument as follows: + -h argument as follows: - $ ~/poky/scripts/create-pull-request --help - $ ~/poky/scripts/send-pull-request --help + $ ~/poky/scripts/create-pull-request -h + $ ~/poky/scripts/send-pull-request -h @@ -1054,8 +1053,8 @@ Here is a general procedure: Make your changes in your local Git repository. - Stage your commit (or change) by using the git add - command. + Stage your changes by using the git add + command on each file you changed. Commit the change by using the git commit --signoff command. Using the --signoff option identifies you as the person -- cgit v1.2.3-54-g00ecf