Follow this procedure to push a change to an upstream "contrib" Git repository:
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:
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
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: (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all 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.
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.
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
Push Your Commits to a "Contrib" Upstream: If you have arranged for permissions to push to an upstream contrib repository, push the change to that repository:
$ git pushupstream_remote_repo
local_branch_name
For example, suppose you have permissions to push into the
upstream meta-intel-contrib
repository and you are working in a local branch named
your_name
/README
.
The following command pushes your local commits to the
meta-intel-contrib
upstream
repository and puts the commit in a branch named
your_name
/README
:
$ git push meta-intel-contrib your_name
/README
Determine Who to Notify: Determine the maintainer or the mailing list that you need to notify for the change.
Before submitting any change, you need to be sure who the maintainer is or what mailing list that you need to notify. Use either these methods to find out:
Maintenance File:
Examine the maintainers.inc
file, which is located in the
Source Directory
at
meta/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.
Examine the List of Mailing Lists: 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 or the mailing list 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
(e.g. ~/poky/scripts
).
Using these scripts correctly formats the requests without introducing any whitespace or HTML formatting. The maintainer that receives your patches either directly or through the mailing list needs to be able to save and apply them directly from your emails. Using these scripts is the preferred method for sending patches.
First, create the pull request. For example, the following command runs the script, specifies the upstream repository in the contrib directory into which you pushed the change, and provides a subject line in the created patch files:
$ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README"
Running this script forms
*.patch
files in a folder named
pull-
PID
in the current directory.
One of the patch files is a cover letter.
Before running the
send-pull-request
script, you must
edit the cover letter patch to insert information about
your change.
After editing the cover letter, send the pull request.
For example, the following command runs the script and
specifies the patch directory and email address.
In this example, the email address is a mailing list:
$ ~/poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org
You need to follow the prompts as the script is interactive.
-h
argument as follows:
$ poky/scripts/create-pull-request -h $ poky/scripts/send-pull-request -h