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. - - 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: - - Maintenance File: - Examine the maintainers.inc file, which is - located in the - Source Directory - at meta-poky/conf/distro/include, to - see who is responsible for code. - - Board Support Package (BSP) README Files: - For BSP maintainers of supported BSPs, you can examine - individual BSP README files. - In addition, some layers (such as the meta-intel layer), - include a MAINTAINERS file which contains - a list of all supported BSP maintainers for that layer. - - Search by File: - Using Git, you can enter the - following command to bring up a short list of all commits - against a specific file: - +
+ Overview + + + 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 + README file that indicates where to send + the changes and which process to follow. + + + + 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. + + + + Specific to OpenEmbedded-Core, two commonly used testing trees + exist: + + + "ross/mut" branch: + The "mut" (master-under-test) tree + exists in the poky-contrib repository + in the + Yocto Project source repositories. + + + "master-next" branch: + This branch is part of the main + "poky" repository in the Yocto Project source repositories. + + + 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. + + + + 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 + Patchwork + to track the status of patches and also to automatically preview + patches. + + + + The following sections provide general instructions for both + pushing changes upstream and for submitting changes as patches. + +
+ +
+ Submissions to Poky + + + 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: + + + 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. + + + BitBake: + For changes to BitBake (i.e. anything under the + bitbake directory), send your patch + to the + bitbake-devel + mailing list. + + + "meta-yocto-bsp" and "meta-poky" trees: + These trees are + part of the "meta-yocto" repository in the Yocto Project + source repositories. + Use the + poky + mailing list. + + + +
+ +
+ Submissions to Other Layers + + + For changes to other layers hosted in the Yocto Project source + repositories (i.e. yoctoproject.org), tools, + and the Yocto Project documentation, use the + Yocto Project + general mailing list. + + Sometimes a layer's documentation specifies to use a + particular mailing list. + If so, use that 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. + the README file) supplied with the layer. + If in doubt, please ask on the Yocto general mailing list or on + the openembedded-devel mailing list. + +
+ +
+ Patch Submission Details + + + When submitting any change, you can check who you should be + notifying. + Use either of these methods to find out: + + + Maintenance File: + Examine the maintainers.inc file, which is + located in the + Source Directory + at meta-poky/conf/distro/include, to + see who is responsible for code. + + + Search by File: + Using Git, you can enter the + following command to bring up a short list of all commits + against a specific file: + git shortlog -- filename - - 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. - - - + + 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. + + + - - For a list of the Yocto Project and related mailing lists, see the - "Mailing lists" section in - the Yocto Project Reference Manual. - + + For a list of the Yocto Project and related mailing lists, see the + "Mailing lists" + section in the Yocto Project Reference Manual. + - - Here is some guidance on which mailing list to use for what type of change: - - 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-poky, 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 that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1 - as follows: - + + 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: + 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. - - + + - - 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. - + + 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. + - - 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: - - 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. - - 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. - - - 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: - + + 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: + + + 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. + + + 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. + + + 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: + Fixes [YOCTO #bug-id] detailed description of change - + + Where bug-id is replaced with the specific bug ID from the Yocto Project Bugzilla instance. - - + + - - You can find more guidance on creating well-formed commit messages at this OpenEmbedded - wiki page: - . - - - - The next two sections describe general instructions for both pushing - changes upstream and for submitting changes as patches. - + + You can find more guidance on creating well-formed commit messages + at this OpenEmbedded wiki page: + . + +
Using Scripts to Push a Change Upstream and Request a Pull