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 (in any particular project).
  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 ## Remember: one patch per email
  37
  38 Every patch should (must!) contain only one bugfix or new feature.
  39
  40 Eric S. Raymond has written good 'Software Release Practice HOWTO'.
  41 Check what he has to say about this issue.
  42
  43 ## Prepare patches for e-mail submission
  44
  45 If you're made just one commit (containing just one bugfix or new feature)
  46 you can run
  47
  48       git format-patch HEAD^
  49
  50 This outputs something like
  51
  52       0001-one-line-description.patch
  53
  54 This is the file name of your patch with content:
  55
  56       From <-40-character-sha1-hexadecimal-string-> Day Mon DD HH:MM:SS YYYY
  57       From: user.name <user.email>
  58       Date: Day, DD Mon YYYY HH:MM:SS TZOFF
  59       Subject: [PATCH] first commit line; one line description, up to 65 chars
  60
  61       after one empty line, a detailed description of your patch
  62       the description most usually spans over multiple lines.
  63       ---
  64        <diffstat lines>
  65        nn files changed, nn insertions(+) nn deletions(-)
  66
  67       diff --git a/<1st filename> b/<1st filename>
  68       ...
  69
  70 If you have committed more patches, and want to prepare all of those
  71 you can check with `git log` a 40-char commit-sha1 of the last commit
  72 *since* you want to generate patch files. When you enter
  73
  74       git format patch commit-sha1(-prefix)
  75
  76 every commit *after* that commit-sha1 will be used to generate
  77 patch files...
  78
  79 ## Sending patches
  80
  81 ### Using git send-email
  82
  83 (This is the preferred way)
  84
  85 If you try to execute `git send-email` and you'll get
  86
  87       git: 'send-email' is not a git command. See 'git --help'.
  88
  89 Then you're using git installation where send-email command is distributed
  90 in separate package. In Debian/Ububtu/RedHat/Fedora the package is named
  91 `git-email`. Use the package manager in your distribution to install this
  92 package (or ask administrator to do this if you don't have privileges to do so).
  93
  94 Playing with `git send-email` is pretty safe. By default it will ask questions,
  95 finally whether the email is to be sent or not. In normal cases you may
  96 just need to set smtp server (in case local sendmail is not configured to
  97 work properly). Check through `git-send-email` manual page and play with it.
  98
  99 In case of one-file you might want to use
 100
 101       git send-email --annotate 0001-*
 102
 103 (other options omitted) to add a 'discussion' part into your
 104 email. The `git am` tool which is eventually used to submit the patch
 105 will ignore anything after first `---` and before the `diff --git ...`
 106 in the mail message (see example content above). In this case be careful
 107 you don't break the commit log message or the patch content.
 108
 109 In case of multi-patch send, `git send-email --compose 00*.patch` can be
 110 used to send an introductory message (as separate email). This also follows
 111 the principle of sending only one patch per mail -- by sending each patch
 112 in separate mails.
 113
 114 After you've played (perhaps with `--dry-run`) a bit, send first test emails
 115 to your own email address to see how the messages appear in your mailbox.
 116 In this phase you can "streamline" your `git send-email` options for
 117 actual patch sending to the mailing list.
 118
 119 ### Sending one patch using compatible (emacs) email client.
 120
 121 One alternative way to send your patches is to use, for example, the
 122 emacs mail client you've already used to send mails to mailing list.
 123 In this case you have to be very careful to keep the patch contents
 124 unchanged:
 125
 126 1. Start composing new mail
 127
 128 2. Enter notmuch mailing list address to To: field.
 129
 130 3. Go to the body part of the email
 131
 132 4. Enter `C-x i` (M-x insert-file) and insert the patch file to the buffer
 133
 134 5. Replace Subject: line from the Subject line of the patch.
 135
 136 6. Remove everything before the description content from the beginning of the body.
 137
 138 7. Fill the discussion part after `---` unless you have done so (and there is anything to discuss).
 139
 140 8. Check your text once more and then enter `C-c C-c` (message-send-and-exit).
 141
 142 When your patches appear on the mailing list read the comments and take part
 143 to the discussion and prepare to do adjustments to your patches.