Patch Formatting

How to Begin

Before you intend to provide patches outside of your local circle you should check the following:

Run git log and examine quite a few commit messages.
Read mailing list (archives) and follow the discussions on the patches sent.
Get familiar with coding conventions used.
Read devel/STYLE in notmuch source.

This way you get some insight of the look and feel of the patches sent, both the way code should be written, how to write commit log messages and how to participate patch discussions.

Committing changes (locally)

After you've been editing your changes under cloned notmuch git repository first commit your changes... preferably (to you) to a separate branch; if you forgot to branch before starting you can do it now -- your modified working tree will follow.

Enter your commit message in following format:

    first commit line; short one line description

    After one empty line, a detailed description of your changes
    the description most usually spans over multiple lines.

Wrap the lines to about 72 characters or so. On an 80 column terminal, if we subtract 4 columns for the indent on the left and 4 more for symmetry on the right, we’re left with 72 columns.

Regarding the commit message body contents, Carl has stated:

The single line summary is good about saying what the commit does, but I always want to see at least one sentence about the why as well.

Activating default pre-commit hook

Git provides a default pre-commit hook which, when activated, checks (at least) for whitespace errors (trailing whitespace and space before tab). It is better to notice this kind of "errors" early than have patch reviewers to mention about those.

The hook, when activated, is named as .git/hooks/pre-commit and it has execute permissions set on. By default, when git tree is cloned your hooks dir may have default, inactive pre-commit hook available as:

.git/hooks/pre-commit without execute permission set
.git/hooks/pre-commit.sample usually with execute permission set

In case of 2, enter cp .git/hooks/pre-commit.sample .git/hooks/pre-commit. And, now enter chmod a+x .git/hooks/pre-commit in case it does not have execute permission set.

Remember: one patch per email

Every patch should (must!) contain only one bugfix or new feature.

Eric S. Raymond has written good Software Release Practice HOWTO. Check what he has to say about this issue.

Test Suite Enhancements

New features as well as bug fixes should typically come with test suite enhancements. The test suite changes should be done first (tagged as expected to fail), and the feature implementation or bug fix should come second (removing the expected to fail tag). This way, the test suite specifies the behavior you're trying to implement, be it a new feature or a bug fix. By defining beforehand exactly what you expect to happen, everyone can confirm that your patch achieves what it is meant it to.

Prepare patches for e-mail submission

If you've made just one commit (containing just one bugfix or new feature) you can run

    git format-patch HEAD^

This outputs something like

    0001-one-line-description.patch

This is the file name of your patch with content:

    From <-40-character-sha1-hexadecimal-string-> Day Mon DD HH:MM:SS YYYY
    From: user.name <user.email>
    Date: Day, DD Mon YYYY HH:MM:SS TZOFF
    Subject: [PATCH] first commit line; one line description, up to 72 chars

    after one empty line, a detailed description of your patch
    the description most usually spans over multiple lines.
    ---
     <diffstat lines>
     nn files changed, nn insertions(+) nn deletions(-)

    diff --git a/<1st filename> b/<1st filename>
    ...

If you have committed more patches, and want to prepare all of those you can check with git log a 40-char commit-sha1 of the last commit since you want to generate patch files. When you enter

    git format-patch <commit-sha1(-prefix)>

every commit after that commit-sha1 will be used to generate patch files...

Test-applying your patches

Sometimes you may face a situation with your patches that you are unsure whether those patches apply to the origin. Such a cases might be:

You've taken your patches from a branch that has some other commits on top of origin.
You have edited the commit message, comments below commit message or the patch content itself in the patch files generated.

To verify that your patches will apply on top of pristine origin you can test-apply your patch files on origin/master:

Simple case -- no other changes on top of origin/master

    git reset --hard origin/master
    git pull
    git am 00*

A case where working tree is dirty

    git log -1 --format=%H > head_commit
    git stash save
    git reset --hard origin/master
    git pull
    git am 00*
    :
    git reset --hard `cat head_commit`
    git stash apply
    rm head_commit
    git stash drop

Sending patches

Using git send-email

(This is the preferred way)

If you try to execute git send-email and you get

    git: 'send-email' is not a git command. See 'git --help'.

Then you're using git installation where send-email command is distributed in separate package. In Debian/Ububtu/RedHat/Fedora the package is named git-email. Use the package manager in your distribution to install this package (or ask administrator to do this if you don't have privileges to do so).

Playing with git send-email is pretty safe. By default it will ask questions, finally whether the email is to be sent or not. In normal cases you may just need to set smtp server (in case local sendmail is not configured to work properly). Check through git-send-email manual page and play with it.

In case of one-file you might want to use

    git send-email --annotate 0001-*

(other options omitted) to add a 'discussion' part into your email. The git am tool which is eventually used to submit the patch will ignore anything after first --- and before the diff --git ... in the mail message (see example content above). In this case be careful you don't break the commit log message or the patch content.

In case of multi-patch send, git send-email --compose 00*.patch can be used to send an introductory message (as separate email). This also follows the principle of sending only one patch per mail -- by sending each patch in separate mails.

After you've played (perhaps with --dry-run) a bit, send first test emails to your own email address to see how the messages appear in your mailbox. In this phase you can "streamline" your git send-email options for actual patch sending to the mailing list.

Sending one patch using compatible (emacs) email client.

Sometimes using git-send-email is not possible; It is not installed by default and you don't have privileges to install it or you are not able to compile it as it has more build-time requirements as git itself.

One alternative way to send your patches is to use, for example, the emacs mail client you've already used to send mails to mailing list. In this case you have to be very careful to keep the patch contents unchanged:

Start composing new mail
Enter notmuch mailing list address into To: field.
Go to the body part of the email
Enter C-x i (M-x insert-file) and insert the patch file to the buffer
Replace Subject: line from the Subject line of the patch.
Remove everything before the description content from the beginning of the body.
Fill the discussion part after --- unless you have done so (and there is anything to discuss).
Check your text once more and then enter C-c C-c (message-send-and-exit).

When your patches appear on the mailing list read the comments and take part to the discussion and prepare to do adjustments to your patches.