3.3.1. Using Scripts to Push a Change Upstream and Request a Pull

Follow this procedure to push a change to an upstream "contrib" Git repository:

Note

You can find general Git information on how to push a change upstream in the Git Community Book.

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

  2. Stage Your Changes: Stage your changes by using the git add command on each file you changed.

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

      Note

      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
                                  

  4. 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 push upstream_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
                        

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

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

    Note

    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