diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml index acb4731282..0bc0be2164 100644 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ b/documentation/dev-manual/dev-manual-newbie.xml @@ -509,18 +509,18 @@ Here are some things to remember when dealing with bugs against the Yocto Project: - - The Yocto Project follows a naming bug-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 when creating a commit comment - would be [YOCTO 1011]. - This convention becomes important if you are submitting patches against the Yocto Project - code itself. - See the following section for more information. - Defects for Yocto Project fall into one of four classifications: Yocto Projects, - Infrastructure, Poky, and Yocto Metadata Layers. - + + The Yocto Project follows a naming bug-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 when creating a commit comment + would be [YOCTO #1011]. + This convention becomes important if you are submitting patches against the Yocto Project + code itself. + See the following section for more information. + Defects for Yocto Project fall into one of four classifications: Yocto Projects, + Infrastructure, Poky, and Yocto Metadata Layers. + @@ -529,9 +529,9 @@ Contributions to the Yocto Project are very welcome. - You should send patches to the Yocto Project mailing list to get it in front of the + You should send patches to the Yocto Project mailing list to get them in front of the Yocto Project Maintainer. - When you send your patch, be sure to include a "signed-off-by:" + 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 as follows: @@ -577,31 +577,67 @@ - When you submit a change or patch to the Yocto Project, you must follow certain procedures. - In particular, the headers in patches and the commit messages must follow a certain standard. - The general process is the same as described earlier in this chapter. - For complete details on how to create proper commit messages and patch headers see - [WRITER NOTE: I need the link to Mark's wiki page here that describes the process.] + When you form a commit you must follow certain standards established by the + Yocto Project development team. + For each commit, do the following: + + Provide a single-line, short summary of the change. + This summary is typically viewable by source control systems. + Thus, providing something short and descriptive that gives the reader + a summary of the change is useful when viewing a list of many commits. + + If the change addresses a specific bug or issue that is + associated with a bug-tracking ID, prefix the single-line commit summary + 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 use a commit summary line in the + following form: + + YOCTO #<bug-id>: <Brief 40-character or less summary of the change> + + 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. + Provide as much detail as you want in the body of the commit message. + + Following are general instructions for both pushing changes upstream and for submitting changes as patches. - +
- Pushing a Change Upstream + Pushing a Change Upstream and Requesting 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 commit (or change) by using the git add - command. - Commit the change by using the git commit - command and push it to the upstream "contrib" repository. - Be sure to provide a commit message that follows the project’s commit standards. - Notify the maintainer that you have pushed a change. - + + Make your changes in your local Git repository. + Stage your commit (or change) by using the git add + command. + Commit the change by using the git commit + command and push it to the upstream "contrib" repository. + Be sure to provide a commit message that follows the project’s commit standards + as described earlier. + 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 of the + Yocto Project file structure. + For help on using these scripts, simply provide the + --help argument as follows: + + $ ~/poky/scripts/create-pull-request --help + $ ~/poky/scripts/send-pull-request --help + + + + + You can find general Git information on how to push a change upstream here. @@ -609,30 +645,56 @@
- Submitting a Patch + Submitting a Patch Through Email - If you have a just a few changes you can commit them and then submit them as an email to the maintainer. + If you have a just a few changes, you can commit them and then submit them as an + email to the maintainer. Here is a general procedure: - - Make your changes in your local Git repository. - Stage your commit (or change) by using the git add - command. - Commit the change by using the git commit command. - Be sure to provide a commit message that follows the project’s commit standards. - Format the commit by using the git format-patch - command. - This step produces a numbered series of files in the current directory – one for - each commit. - Import the files into your mail client by using the - git-send-email command. - Send the email by hand to the maintainer. - - Be aware that there could be protocols and standards that you need to follow for your particular - project. - You can find general Git information for submitting a patch - - here. + + Make your changes in your local Git repository. + Stage your commit (or change) by using the git add + command. + Commit the change by using the + git commit --signoff command. + Using the --signoff option identifies you as the person + making the change. + When you form a commit you must follow certain standards established by the + Yocto Project development team. + See the + How to Submit a Change section + earlier for Yocto Project commit message standards. + Format the commit into an email messsage. + To format commits, use the git format-patch command. + When you provide the command, you must include a revision list or a number of patches + as part of the command. + For example, these two commands each take the most recent single commit and + format it as an email message in the current directory: + + $ git format-patch -1 + $ 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, it produces a numbered + series of files in the current directory – one for each commit. + For information on the git format-patch command use the + man git-format-patch command. + Import the files into your mail client by using the + git send-email command. + In order to use git send-email, you must have the + the proper Git packages installed. + For Ubuntu 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, sendmail, or through a direct + smtp configuration in your Git config + file. + The git send-email command has several options that let you + specify recipients and perform further editing of the email message. + For information on how to use the git send-email command, + use the man git-send-email command. +