2. Read mailing list (archives) and follow the discussions on the patches sent.
-3. Get familiar with coding conventions used (in any particular project).
+3. Get familiar with coding conventions used.
+
+4. 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
Enter your commit message in following format:
- first commit line; one line description, up to 65 chars
+ 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.
+ 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](http://article.gmane.org/gmane.mail.notmuch.general/504):
+
+> 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 65-character (limit) seems to be common among many projects so
-that is good guideline to follow here too.
+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:
+
+1. .git/hooks/pre-commit without execute permission set
+
+2. .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'.
+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.
+### 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're made just one commit (containing just one bugfix or new feature)
+If you've made just one commit (containing just one bugfix or new feature)
you can run
- git format-patch HEAD^
+ git format-patch HEAD^
This outputs something like
- 0001-one-line-description.patch
+ 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 65 chars
+ 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(-)
+ 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>
- ...
+ 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)
+ git format-patch <commit-sha1(-prefix)>
every commit *after* that commit-sha1 will be used to generate
patch files...
-## Using git send-email to send patches.
+### 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:
-If you try to execute `git send-email` and you'll get
+* You've taken your patches from a branch that has some other commits on top of origin.
- git: 'send-email' is not a git command. See 'git --help'.
+* 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
In case of one-file you might want to use
- git send-email --annotate 0001-*
+ 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
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.
+### 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 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
projects / obsolete / notmuch-wiki / blobdiff