X-Git-Url: https://git.cworth.org/git?p=obsolete%2Fnotmuch-wiki;a=blobdiff_plain;f=patchformatting.mdwn;h=ed15b9f83bf1457ca0cbaf96bb81832061c370a4;hp=a61c41aca24d67deee34e6732a887e6124856b39;hb=HEAD;hpb=4f967138b317bc77b0a87b7f02a801707397e9b2 diff --git a/patchformatting.mdwn b/patchformatting.mdwn index a61c41a..ed15b9f 100644 --- a/patchformatting.mdwn +++ b/patchformatting.mdwn @@ -10,7 +10,9 @@ you should check the following: 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 @@ -25,62 +27,135 @@ working tree will follow. 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 - 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 + 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. - --- - - 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. + --- + + 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 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 @@ -94,7 +169,7 @@ 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-* + 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 @@ -112,16 +187,20 @@ 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. +### 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