git.cworth.org Git - notmuch-wiki/blob - patchformatting.mdwn

   1 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
   2 # Patch Formatting
   3
   4 ## How to Begin
   5
   6 Before you intend to provide patches outside of your local circle
   7 you should check the following:
   8
   9 1. Run `git log` and examine quite a few commit messages.
  10
  11 2. Read mailing list (archives) and follow the discussions on the patches sent.
  12
  13 3. Get familiar with coding conventions used.
  14
  15 This way you get some insight of the look and feel of the patches sent,
  16 both the way code should be written, how to write commit log messages
  17 and how to participate patch discussions.
  18
  19 ## Committing changes (locally)
  20
  21 After you've been editing your changes under cloned notmuch git repository
  22 first commit your changes... preferably (to you) to a separate branch;
  23 if you forgot to branch before starting you can do it now -- your modified
  24 working tree will follow.
  25
  26 Enter your commit message in following format:
  27
  28       first commit line; one line description, up to 65 chars
  29
  30       After one empty line, a detailed description of your changes
  31       the description most usually spans over multiple lines.
  32
  33 The 65-character (limit) seems to be common among many projects so
  34 that is good guideline to follow here too.
  35
  36 Regarding the commit message body contents, Carl [has stated](http://article.gmane.org/gmane.mail.notmuch.general/504):
  37
  38 > The single line summary is good about saying *what* the commit does,
  39 > but I always want to see at least one sentence about the *why* as well.
  40
  41 ### Activating default pre-commit hook
  42
  43 Git provides a default pre-commit hook which, when activated, checks
  44 (at least) for whitespace errors (trailing whitespace and space before
  45 tab). It is better to notice this kind of "errors" early than have
  46 patch reviewers to mention about those.
  47
  48 The hook, when activated, is named as .git/hooks/pre-commit and it
  49 has execute permissions set on. By default, when git tree is cloned
  50 your hooks dir may have default, inactive pre-commit hook available
  51 as:
  52
  53 1. .git/hooks/pre-commit  without execute permission set
  54
  55 2. .git/hooks/pre-commit.sample  usually with execute permission set
  56
  57 In case of 2, enter `cp .git/hooks/pre-commit.sample .git/hooks/pre-commit`.
  58 And, now enter `chmod a+x .git/hooks/pre-commit` in case it does not
  59 have execute permission set.
  60
  61 ## Remember: one patch per email
  62
  63 Every patch should (must!) contain only one bugfix or new feature.
  64
  65 Eric S. Raymond has written good
  66 [Software Release Practice HOWTO](http://tldp.org/HOWTO/Software-Release-Practice-HOWTO/).
  67 Check what he has to say about this issue.
  68
  69 ### Test Suite Enhancements
  70
  71 New features as well as bug fixes should typically come with test suite
  72 enhancements.  The test suite changes should be done first (tagged as *expected
  73 to fail*), and the feature implementation or bug fix should come second
  74 (removing the *expected to fail* tag).  This way, the test suite specifies the
  75 behavior you're trying to implement, be it a new feature or a bug fix.  By
  76 defining beforehand exactly what you expect to happen, everyone can confirm
  77 that your patch achieves what it is meant it to.
  78
  79 ## Prepare patches for e-mail submission
  80
  81 If you've made just one commit (containing just one bugfix or new feature)
  82 you can run
  83
  84       git format-patch HEAD^
  85
  86 This outputs something like
  87
  88       0001-one-line-description.patch
  89
  90 This is the file name of your patch with content:
  91
  92       From <-40-character-sha1-hexadecimal-string-> Day Mon DD HH:MM:SS YYYY
  93       From: user.name <user.email>
  94       Date: Day, DD Mon YYYY HH:MM:SS TZOFF
  95       Subject: [PATCH] first commit line; one line description, up to 65 chars
  96
  97       after one empty line, a detailed description of your patch
  98       the description most usually spans over multiple lines.
  99       ---
 100        <diffstat lines>
 101        nn files changed, nn insertions(+) nn deletions(-)
 102
 103       diff --git a/<1st filename> b/<1st filename>
 104       ...
 105
 106 If you have committed more patches, and want to prepare all of those
 107 you can check with `git log` a 40-char commit-sha1 of the last commit
 108 *since* you want to generate patch files. When you enter
 109
 110       git format-patch <commit-sha1(-prefix)>
 111
 112 every commit *after* that commit-sha1 will be used to generate
 113 patch files...
 114
 115 ## Sending patches
 116
 117 ### Using git send-email
 118
 119 (This is the preferred way)
 120
 121 If you try to execute `git send-email` and you get
 122
 123       git: 'send-email' is not a git command. See 'git --help'.
 124
 125 Then you're using git installation where send-email command is distributed
 126 in separate package. In Debian/Ububtu/RedHat/Fedora the package is named
 127 `git-email`. Use the package manager in your distribution to install this
 128 package (or ask administrator to do this if you don't have privileges to do so).
 129
 130 Playing with `git send-email` is pretty safe. By default it will ask questions,
 131 finally whether the email is to be sent or not. In normal cases you may
 132 just need to set smtp server (in case local sendmail is not configured to
 133 work properly). Check through `git-send-email` manual page and play with it.
 134
 135 In case of one-file you might want to use
 136
 137       git send-email --annotate 0001-*
 138
 139 (other options omitted) to add a 'discussion' part into your
 140 email. The `git am` tool which is eventually used to submit the patch
 141 will ignore anything after first `---` and before the `diff --git ...`
 142 in the mail message (see example content above). In this case be careful
 143 you don't break the commit log message or the patch content.
 144
 145 In case of multi-patch send, `git send-email --compose 00*.patch` can be
 146 used to send an introductory message (as separate email). This also follows
 147 the principle of sending only one patch per mail -- by sending each patch
 148 in separate mails.
 149
 150 After you've played (perhaps with `--dry-run`) a bit, send first test emails
 151 to your own email address to see how the messages appear in your mailbox.
 152 In this phase you can "streamline" your `git send-email` options for
 153 actual patch sending to the mailing list.
 154
 155 ### Sending one patch using compatible (emacs) email client.
 156
 157 Sometimes using git-send-email is not possible; It is not installed by
 158 default and you don't have privileges to install it or you are not
 159 able to compile it as it has more build-time requirements as git itself.
 160
 161 One alternative way to send your patches is to use, for example, the
 162 emacs mail client you've already used to send mails to mailing list.
 163 In this case you have to be very careful to keep the patch contents
 164 unchanged:
 165
 166 1. Start composing new mail
 167
 168 2. Enter notmuch mailing list address into To: field.
 169
 170 3. Go to the body part of the email
 171
 172 4. Enter `C-x i` (M-x insert-file) and insert the patch file to the buffer
 173
 174 5. Replace Subject: line from the Subject line of the patch.
 175
 176 6. Remove everything before the description content from the beginning of the body.
 177
 178 7. Fill the discussion part after `---` unless you have done so (and there is anything to discuss).
 179
 180 8. Check your text once more and then enter `C-c C-c` (message-send-and-exit).
 181
 182 When your patches appear on the mailing list read the comments and take part
 183 to the discussion and prepare to do adjustments to your patches.