X-Git-Url: https://git.cworth.org/git?p=notmuch-wiki;a=blobdiff_plain;f=patchformatting.mdwn;h=dda840feb96e5cfdc939a95d71cef27a9a533645;hp=997f3f208372e327e6520a35785597660c5d7df1;hb=f5ddc01eb0181124a8449a12afe2587e2304e6fb;hpb=950944ba197f40df443c4b5bd85708ab6afbcf39 diff --git a/patchformatting.mdwn b/patchformatting.mdwn index 997f3f2..dda840f 100644 --- a/patchformatting.mdwn +++ b/patchformatting.mdwn @@ -1,165 +1,208 @@ [[!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 +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. -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. +## Committing changes (locally) -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. +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. -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. +Enter your commit message in following format: -## 3. Email body contents: patch + 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. -### Sub-Rule Number One: +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. -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. +Regarding the commit message body contents, +Carl [has stated](http://article.gmane.org/gmane.mail.notmuch.general/504): -### Sub-Rule Number Two: +> 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. -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). +### Activating default pre-commit hook -### Sub-Rule Number Three: +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. -Patch must be rooted one level above notmuch source tree. i.e. +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: - 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 +1. .git/hooks/pre-commit without execute permission set -or in other words, the patch must be apply-able using +2. .git/hooks/pre-commit.sample usually with execute permission set - patch -sp1 < foo.patch +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. -## 4. One patch per email +## Remember: one patch per email -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. +Every patch should (must!) contain only one bugfix or new feature. -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. +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. -## 5. Sign your work +### Test Suite Enhancements -( currently notmuch in use ) +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. -## 6. Avoid attachments and MIME +## Prepare patches for e-mail submission -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. +If you've made just one commit (containing just one bugfix or new feature) +you can run -## 7. Follow these instructions even when resending + git format-patch HEAD^ -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. +This outputs something like -For more details, read Documentation/SubmittingPatches -in the linux kernel source tree. + 0001-one-line-description.patch +This is the file name of your patch with content: -## Tips for producing and sending your patches. + 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 -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. + 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(-) -Then write your commit message with the rules above, i.e. + diff --git a/<1st filename> b/<1st filename> + ... - 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. +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 -Now that you're committed your changes, enter + git format-patch - git format-patch HEAD^ +every commit *after* that commit-sha1 will be used to generate +patch files... -This outputs something like +### Test-applying your patches - 0001-one-line-description.patch +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: -This is the file name of your patch with content: +* 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 - 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. - --- - - 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. @@ -167,7 +210,7 @@ unchanged: 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.