[[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
# Patch Formatting
-## How to Begin
-
-Before you intend to provide patches outside of your local circle
-you should check the following:
-
-1. Run `git log` and examine quite a few commit messages.
-
-2. Read mailing list (archives) and follow the discussions on the patches sent.
-
-3. Get familiar with coding conventions used.
-
-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; one line description, up to 65 chars
-
- After one empty line, a detailed description of your changes
- the description most usually spans over multiple lines.
-
-The 65-character (limit) seems to be common among many projects so
-that is good guideline to follow here too.
-
-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 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](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'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 65 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...
-
-## 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:
-
-1. Start composing new mail
-
-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
-
-5. Replace Subject: line from the Subject line of the patch.
-
-6. Remove everything before the description content from the beginning of the body.
-
-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).
-
-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.
+Please refer to the [[guide to contributing|contributing]].
projects / notmuch-wiki / blobdiff