X-Git-Url: https://git.cworth.org/git?p=notmuch-wiki;a=blobdiff_plain;f=patchformatting.mdwn;h=ac9481153a874b820b536cb4a4e119494ca0b8a6;hp=cf5bf813c082337c0e3f2799b3f12f1588ef184a;hb=HEAD;hpb=889266d3dfcd3f478978cf136a94f3448696999a diff --git a/patchformatting.mdwn b/patchformatting.mdwn index cf5bf81..ac94811 100644 --- a/patchformatting.mdwn +++ b/patchformatting.mdwn @@ -1,148 +1,4 @@ [[!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. - -## 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. - -## 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 - 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. - --- - - 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 - -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]].