3.31.2.2. 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. 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 at 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:

  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 --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 Step 3 in the previous section for information on how to provide commit information that meets Yocto Project commit message standards.

  4. 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 list or a number of patches as part of the command. For example, either of these two commands takes your most recent single commit and formats it as an email message in the current directory:

         $ git format-patch -1
                                

    or

         $ 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 directory – one for each commit. If you have more than one patch, you should also use the --cover option with the command, which generates a cover letter as the first "patch" in the series. You can then edit the cover letter to provide a description for the series of patches. For information on the git format-patch command, see GIT_FORMAT_PATCH(1) displayed using the man git-format-patch command.

    Note

    If you are or will be a frequent contributor to the Yocto Project or to OpenEmbedded, you might consider requesting a contrib area and the necessary associated rights.

  5. Import the Files Into Your Mail Client: Import the files into your mail client by using the git send-email command.

    Note

    In order to use git send-email, you must have the proper Git packages installed on your host. 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, sendmail, or through a direct smtp configuration in your Git ~/.gitconfig file. If you are submitting patches through email only, it is very important that you submit them without any whitespace or HTML formatting that either you or your mailer introduces. The maintainer that receives your patches needs to be able to save and apply them directly from your emails. A good way to verify that what you are sending will be 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 using email since there is no risk of compromising whitespace in the body of the message, which can occur when you use your own mail client. The command also 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, see GIT-SEND-EMAIL(1) displayed using the man git-send-email command.