[[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
# Patch Formatting
-This text is mostly based on
-[http://linux.yyz.us/patch-format.html](http://linux.yyz.us/patch-format.html);
- here modified to the simplest case possible that is suitable in this
-software. `git format-patch` produces base for this kind of patches.
-See mailing list archives for somewhat more complex scenarios. At the
-end there are some tips how to get your patches sent.
+## How to Begin
-## 1. Email subject format
+Before you intend to provide patches outside of your local circle
+you should check the following:
-The subject line has format:
+1. Run `git log` and examine quite a few commit messages.
- [PATCH] one line summary
+2. Read mailing list (archives) and follow the discussions on the patches sent.
-I.e: a constant prefix `[PATCH]` followed by one line summary. The
-65-character limit seems to be common among many projects so that
-is good guideline to follow here too.
+3. Get familiar with coding conventions used.
-## 2. Email body contents: description
+4. Read `devel/STYLE` in notmuch source.
-At the beginning of your email, use as many lines as you wish to
-describe the patch. This text is copied directly into the SCM
-(i.e. git) changelog.
+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.
-Include comments and other data (such as diffstat) you don't wish to
-be in the kernel changelog following a `---` terminator line. The
-terminator must be on a line by itself.
+## Committing changes (locally)
-If you run `git log` on your cloned notmuch repository you see how log
-messages get structured from Subject: line and body contents. One
-description line, one empty line and then, usually multiline description
-following. Conversely, notmuch-wiki git log messages are often just one
-line long -- as the description (and the reasoning for it) is usually
-the content itself.
+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.
-## 3. Email body contents: patch
+Enter your commit message in following format:
-### Sub-Rule Number One:
+ 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.
-Patches must be reviewable in a standard Linux email client. This
-means in particular, no compression and no base64
-encoding. Attachments are discouraged, but some corporate mail systems
-provide no other way to send patches.
+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.
-### Sub-Rule Number Two:
+Regarding the commit message body contents,
+Carl [has stated](http://article.gmane.org/gmane.mail.notmuch.general/504):
-Patch must be apply-able by a script that has no knowledge of [MIME]
-encoding. You must make sure your mailer does not escape standard
-US-ASCII characters, wrap long lines, or encode plaintext patches in
-base64 (or any other encoding).
+> 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.
-### Sub-Rule Number Three:
+### Activating default pre-commit hook
-Patch must be rooted one level above notmuch source tree. i.e.
+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.
- diff --git a/emacs/notmuch-mua.el b/emacs/notmuch-mua.el
- index 556d2bf..274c5da 100644
- --- a/emacs/notmuch-mua.el
- +++ b/emacs/notmuch-mua.el
+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:
-or in other words, the patch must be apply-able using
+1. .git/hooks/pre-commit without execute permission set
- patch -sp1 < foo.patch
+2. .git/hooks/pre-commit.sample usually with execute permission set
-## 4. One patch per email
+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.
-This cannot be stressed enough. Even when you are resending a change
-for the 5th time, resist the urge to attach 20 patches to a single
-email. If you do send multiple emails, make sure the second and
-subsequent emails are sent as replies to the first, to keep them all
-together in a thread.
+## Remember: one patch per email
-The mailing list archive & the above link to linux patch formatting
-guidelines are good source of information how to format more complex
-subject line for set of related patches.
+Every patch should (must!) contain only one bugfix or new feature.
-## 5. Sign your work
+Eric S. Raymond has written good
+[Software Release Practice HOWTO](http://tldp.org/HOWTO/Software-Release-Practice-HOWTO/).
+Check what he has to say about this issue.
-( currently notmuch in use )
+### Test Suite Enhancements
-## 6. Avoid attachments and MIME
+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.
-Attachments make it more difficult to review and comment on your
-patches. MIME (the mechanism by which files are attached to an email)
-has historically created a problem for patch import scripts. Some
-unfortunate email programs insist upon base64 encoding for all
-attachments, which completely shrouds the patch to some scripts and
-mailers.
+## Prepare patches for e-mail submission
-## 7. Follow these instructions even when resending
+If you've made just one commit (containing just one bugfix or new feature)
+you can run
-Quite often, when a patch receives comments, the patch author will
-(deep in an email thread) include a revised version of their patch but
-omit the email subject one-line summary, and overall patch
-description. This isn't script friendly, and requires the patch
-description to be hand-edited.
+ git format-patch HEAD^
-For more details, read Documentation/SubmittingPatches
-in the linux kernel source tree.
+This outputs something like
+ 0001-one-line-description.patch
-## Tips for producing and sending your patches.
+This is the file name of your patch with content:
-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.
+ 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
-Then write your commit message with the rules above, i.e.
+ 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(-)
- first commit line; one line description, up to 65 chars
-
- after one empty line, a detailed description of your patch
- the description most usually spans over multiple lines.
+ diff --git a/<1st filename> b/<1st filename>
+ ...
-Now that you're committed your changes, enter
+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 HEAD^
+ git format-patch <commit-sha1(-prefix)>
-This outputs something like
+every commit *after* that commit-sha1 will be used to generate
+patch files...
- 0001-one-line-description.patch
+### Test-applying your patches
-This is the file name of your patch with content:
+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-*
- 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 65 chars
+(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.
- 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(-)
+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.
- diff --git a/<1st filename> b/<1st filename>
- ...
+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.
-Now, after that `---` line and before first `diff --git ...` line
-any discussion about the patch can be started by the patch supplier;
-those lines are ignored by `git am` tool which is (eventually) used to
-apply the patch to the repository.
+### Sending one patch using compatible (emacs) email client.
-If you have `git send-email` command available (and you can send emails
-from any of your shell accounts) you can use that to send your patches.
-Read the `git-send-email` manual page for information how to do so.
+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 notmuch mailing list.
+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:
1. Start composing new mail
-2. Enter notmuch mailing list address to To: field.
+2. Enter notmuch mailing list address into To: field.
3. Go to the body part of the email
-4. Enter C-x i (M-x insert-file) and insert the patch file to the buffer
+4. Enter `C-x i` (M-x insert-file) and insert the patch file to the buffer
5. Replace Subject: line from the Subject line of the patch.
7. Fill the discussion part after `---` unless you have done so (and there is anything to discuss).
-8. Check your text once more and then enter C-c C-c (message-send-and-exit).
+8. 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.
projects / obsolete / notmuch-wiki / blobdiff