Submitting patches via the Mailing List

You may want to do this

• if gerrit is down or unavailable
• if you are submitting changes to system components which are not Baserock software i.e. projects mirrored in the delta/* repos on git.baserock.org)
• if you don't have the time or inclination to register for gerrit

Sending patches for review via the Mailing List, and requesting they be merged

The preferred format for sending patches to be reviewed and merged is that of git format-patch. A cover letter is required and each element of the patch series should be sent as a reply to the cover letter.

The cover letter must contain the following:

1. The location of the repository containing the actual commits.
2. The name of the branch that contains the commits
3. The sha1 sum of the tip of the branch to be reviewed. This should be the sha1 of the commit at the end of the patch chain.

Note, you should NOT tag development branches and by default reviewers will not operate from tags, only from branches (refs starting refs/heads/).

Many email clients cannot properly handle patches. The Linux kernel documentation contains some hints on [configuring email clients][cec].

You can then use git format-patch to produce the patch files and then import them into your mail client before sending them to the [development list].

Using git send-email

You may find that using git send-email is preferable to using your normal email client for the purpose of preparing and sending your patches to the list for review. If you are using a [Debian] derived distribution then you can get the git send-email tool by installing the git-email package.

At this time, git send-email is not available in Baserock and it is also not essential that you use it to generate the patches. There are other ways but if you do not use git send-email or git format-patch directly then you may have issues when it comes to getting your patches reviewed and merged.

Configuring git send-email

You will need to configure a number of items for git send-email to function usefully. At minimum, you need to tell it how to actually send emails. This can be done with the following

git config --global sendemail.smtpserver mail.example.com
git config --global sendemail.smtpserverport 25

If you need encryption to use your mail server, set:

git config --global sendemail.smtpencryption starttls

If you need to log in to your server, you can set the user name in the config and then git send-email will prompt you for the password during the sending process.

git config --global sendemail.smtpuser yourmailusername

You need to teach git send-email what name and address to send the emails from. This might need to change from project to project, but if not, then:

git config --global sendemail.from "$(git config user.name) <$(git config user.email)>"

It makes sense, however, to only configure the destination address within the git repositories you are asking for review. This means that you won't accidentally send reviews for other projects to the Baserock mailing lists.

git config sendemail.to baserock-dev@baserock.org

Sending patches

To send a patch to the list for review/merge, run:

git send-email --suppress-cc=all --annotate --cover-letter origin/master

Where origin/master is the branch you wish to land the patches into. The git send-email program will then calculate the set of patches to be sent and offer you an editor for writing your cover letter.

Remember to set the subject line and body of the cover letter appropriately. The body MUST contain the above listed information (repository url, branch name and commit sha1).

When sending revised versions of a patch series, please prepend a version number ("V2", "V3" etc.) in the subject line of the cover letter. Please also use the --in-reply-to=<message-id> option when sending revised patches: if you set message-id to the message-id of your original posting (which can be found in the mail headers), the newer version will appear as a reply to the original thread instead of startng a new one. thread, instead of appearing as new emails.

Dealing with reviews

A Baserock developer will review your work, and if it needs changes in order to be ready for merging, they will reply to the patches on the mailing list. Please be responsive to their requests as without the changes they request (or an acceptable reason why their request is not appropriate) the patch will not be merged. You may end up needing make substantive changes to your branch and then you should re-issue the review once the discussion has ceased around your previous thread. It is quite acceptable for a set of patches to need several rounds of review before it is merged and you should not lose hope.

Merging your patches

A Baserock developer who has reviewed your contribution will then merge your work to the master or baserock/morph branch as appropriate. They will notify you by emailing the list, replying to the review thread when they have done this, and at that point you are invited to update from the merged branch and delete your merged refs so that they do not litter the namespace unnecessarily.

Merge commit messages should contain Reviewed-By: lines at the end of the commit message gathered from the review mail in the thread. For example:

Merge branch 'sam/ensure-git-directory-exists'

Reviewed-By: Adam Coldrick <adam.coldrick@codethink.co.uk>
Reviewed-By: Francisco Redondo Marchena <francisco.marchena@codethink.co.uk>

Note to reviewers: it is required that all patches that are merged receive a reply on the list to say that they have been merged.

---