diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml index 179a62d95a..1bb82b711d 100644 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ b/documentation/dev-manual/dev-manual-newbie.xml @@ -444,189 +444,180 @@ 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 mailing list so that they - can be reviewed and merged by the appropriate maintainer. + Because the system is extremely configurable and flexible, we recognize + that developers will want to extend, configure or optimize it for + their specific uses. -
- Overview + + The Yocto Project uses a mailing list and a 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. + You should send patches to the appropriate mailing list so that they + can be reviewed and merged by the appropriate maintainer. + 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. + - - 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. + - - 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. - + + 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. + + + - - 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. - + + 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. + - - This system is imperfect and patches can sometimes get lost in the + + You can also push a change upstream and request a maintainer to + pull the change into the component's upstream repository. + You do this by pushing to a contribution repository that is upstream. + See the + "Workflows" + section in the Yocto Project Reference Manual for additional + concepts on working in the Yocto Project development environment. + + + + Two commonly used testing repositories exist for + OpenEmbedded-Core: + + + "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 changes 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. + Asking about the status of a patch or change is reasonable if the + change 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 procedures for submitting a change. + + +
+ Using Scripts to Push a Change Upstream and Request a Pull - 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. + Follow this procedure to push a change to an upstream "contrib" + Git repository: - Sometimes a layer's documentation specifies to use a - particular mailing list. - If so, use that list. + You can find general Git information on how to push a change + upstream in the + Git Community Book. - 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. + Make Your Changes Locally: + Make your changes in your local Git repository. + You should make small, controlled, isolated 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. - 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 everyone who has committed grouped by - name. - From the list, you can see who is responsible for the bulk of - the changes against the file. + Stage Your Changes: + Stage your changes by using the git add + command on each file you changed. - - - - - For a list of the Yocto Project and related mailing lists, see the - "Mailing lists" - section in the Yocto Project Reference Manual. - - - - 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: - + + Commit Your Changes: + Commit the change by using the + git commit command. + Make sure your commit information follows standards by + following these accepted conventions: + + + 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: @@ -652,121 +643,133 @@ 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 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. - 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. - Be sure to use the actual bug-tracking ID from - Bugzilla for - bug-id: - + + + + Provide a single-line summary of the change. + and, + if more explanation is needed, provide more + detail in the body of the commit. + 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. + + You do not need to provide a more detailed + explanation of a change if the change is + minor to the point of the single line + summary providing all the information. + + + + 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. + Be sure to use the actual bug-tracking ID from + Bugzilla for + bug-id: + Fixes [YOCTO #bug-id] detailed description of change - - - - - - - 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 - - - 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 changes by using the git add - command on each file you changed. - - Commit the change by using the - git commit command. - Be sure to provide a commit message that follows the - project’s commit message standards as described earlier. + + + + Push Your Commits to a "Contrib" Upstream: Push the change to the upstream "contrib" repository by using the git push command. - Notify the maintainer that you have pushed a change by making a pull - request. - The Yocto Project provides two scripts that conveniently let you generate and send - pull requests to the Yocto Project. - These scripts are create-pull-request and - send-pull-request. - You can find these scripts in the scripts directory - within the Source Directory. - Using these scripts correctly formats the requests without introducing any - whitespace or HTML formatting. - The maintainer that receives your patches needs to be able to save and apply them - directly from your emails. - Using these scripts is the preferred method for sending patches. + + Determine Who to Notify: + Determine the maintainer that you need to notify for + the change. + + Before submitting any change, you need to be sure + who the maintainer is that you need to notify. + 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 everyone who has + committed 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. + + + Make a Pull Request: + Notify the maintainer that you have pushed a change by + making a pull request. + + The Yocto Project provides two scripts that + conveniently let you generate and send pull requests to the + Yocto Project. + These scripts are create-pull-request + and send-pull-request. + You can find these scripts in the + scripts directory within the + Source Directory. + + + Using these scripts correctly formats the requests + without introducing any whitespace or HTML formatting. + The maintainer that receives your patches needs to be + able to save and apply them directly from your emails. + Using these scripts is the preferred method for sending + patches. + For help on using these scripts, simply provide the -h argument as follows: $ poky/scripts/create-pull-request -h $ poky/scripts/send-pull-request -h - - - - - - You can find general Git information on how to push a change upstream in the - Git Community Book. + + +
@@ -774,49 +777,63 @@ Using Email to Submit a Patch - You can submit patches without using the create-pull-request and - send-pull-request scripts described in the previous section. + You can submit patches without using the + create-pull-request and + send-pull-request scripts described in the + previous section. However, keep in mind, the preferred method is to use the scripts. Depending on the components changed, you need to submit the email to a specific mailing list. - For some guidance on which mailing list to use, see the list in the - "How to Submit a Change" - section. - For a description of the available mailing lists, see the + For some guidance on which mailing list to use, see the + beginning + of this section. + For a description of all the available mailing lists, see the "Mailing Lists" section in the Yocto Project Reference Manual. - Here is the general procedure on how to submit a patch through email without using the - scripts: + Here is the general procedure on how to submit a patch through + email without using the scripts: + Make Your Changes Locally: Make your changes in your local Git repository. + You should make small, controlled, isolated 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. - Stage your changes by using the - git add command on each file you - changed. + Stage Your Changes: + Stage your changes by using the git add + command on each file you changed. + Commit Your Changes: Commit the change by using the git commit --signoff command. Using the --signoff option identifies you as the person making the change and also satisfies the Developer's Certificate of Origin (DCO) shown earlier. + When you form a commit, you must follow certain standards established by the Yocto Project development team. - See the earlier section - "How to Submit a Change" - for Yocto Project commit message standards. + See + Step 3 + in the previous section for information on how to + provide commit information that meets Yocto Project + commit message standards. - Format the commit into an email message. + + Format the Commit: + Format the commit into an email message. To format commits, use the git format-patch command. When you provide the command, you must include a revision @@ -831,9 +848,11 @@ $ git format-patch HEAD~ + After the command is run, the current directory contains a numbered .patch file for the commit. + If you provide several commits as part of the command, the git format-patch command produces a series of numbered files in the current @@ -857,6 +876,7 @@ + Import the Files Into Your Mail Client: Import the files into your mail client by using the git send-email command. @@ -866,6 +886,7 @@ For Ubuntu, Debian, and Fedora the package is git-email. + The git send-email command sends email by using a local or remote Mail Transport Agent (MTA) such as msmtp, @@ -882,6 +903,7 @@ applicable by the maintainer is to do a dry run and send them to yourself and then save and apply them as the maintainer would. + The git send-email command is the preferred method for sending your patches since there is no risk of compromising whitespace in the body of the