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.
+