Documentation / SubmittingPatcheson commit Merge master.kernel.org:/pub/scm/gitk/gitk (03f99c0)
   1I started reading over the SubmittingPatches document for Linux
   2kernel, primarily because I wanted to have a document similar to
   3it for the core GIT to make sure people understand what they are
   4doing when they write "Signed-off-by" line.
   5
   6But the patch submission requirements are a lot more relaxed
   7here on the technical/contents front, because the core GIT is
   8thousand times smaller ;-).  So here is only the relevant bits.
   9
  10
  11(1) Make separate commits for logically separate changes.
  12
  13Unless your patch is really trivial, you should not be sending
  14out a patch that was generated between your working tree and
  15your commit head.  Instead, always make a commit with complete
  16commit message and generate a series of patches from your
  17repository.  It is a good discipline.
  18
  19Describe the technical detail of the change(s).
  20
  21If your description starts to get too long, that's a sign that you
  22probably need to split up your commit to finer grained pieces.
  23
  24Oh, another thing.  I am picky about whitespaces.  Make sure your
  25changes do not trigger errors with the sample pre-commit hook shipped
  26in templates/hooks--pre-commit.
  27
  28
  29(2) Generate your patch using git tools out of your commits.
  30
  31git based diff tools (git, Cogito, and StGIT included) generate
  32unidiff which is the preferred format.
  33
  34You do not have to be afraid to use -M option to "git diff" or
  35"git format-patch", if your patch involves file renames.  The
  36receiving end can handle them just fine.
  37
  38Please make sure your patch does not include any extra files
  39which do not belong in a patch submission.  Make sure to review
  40your patch after generating it, to ensure accuracy.  Before
  41sending out, please make sure it cleanly applies to the "master"
  42branch head.  If you are preparing a work based on "next" branch,
  43that is fine, but please mark it as such.
  44
  45
  46(3) Sending your patches.
  47
  48People on the git mailing list need to be able to read and
  49comment on the changes you are submitting.  It is important for
  50a developer to be able to "quote" your changes, using standard
  51e-mail tools, so that they may comment on specific portions of
  52your code.  For this reason, all patches should be submitted
  53"inline".  WARNING: Be wary of your MUAs word-wrap
  54corrupting your patch.  Do not cut-n-paste your patch; you can
  55lose tabs that way if you are not careful.
  56
  57It is a common convention to prefix your subject line with
  58[PATCH].  This lets people easily distinguish patches from other
  59e-mail discussions.
  60
  61"git format-patch" command follows the best current practice to
  62format the body of an e-mail message.  At the beginning of the
  63patch should come your commit message, ending with the
  64Signed-off-by: lines, and a line that consists of three dashes,
  65followed by the diffstat information and the patch itself.  If
  66you are forwarding a patch from somebody else, optionally, at
  67the beginning of the e-mail message just before the commit
  68message starts, you can put a "From: " line to name that person.
  69
  70You often want to add additional explanation about the patch,
  71other than the commit message itself.  Place such "cover letter"
  72material between the three dash lines and the diffstat.
  73
  74Do not attach the patch as a MIME attachment, compressed or not.
  75Do not let your e-mail client send quoted-printable.  Many
  76popular e-mail applications will not always transmit a MIME
  77attachment as plain text, making it impossible to comment on
  78your code.  A MIME attachment also takes a bit more time to
  79process.  This does not decrease the likelihood of your
  80MIME-attached change being accepted, but it makes it more likely
  81that it will be postponed.
  82
  83Exception:  If your mailer is mangling patches then someone may ask
  84you to re-send them using MIME, that is OK.
  85
  86Do not PGP sign your patch, at least for now.  Most likely, your
  87maintainer or other people on the list would not have your PGP
  88key and would not bother obtaining it anyway.  Your patch is not
  89judged by who you are; a good patch from an unknown origin has a
  90far better chance of being accepted than a patch from a known,
  91respected origin that is done poorly or does incorrect things.
  92
  93If you really really really really want to do a PGP signed
  94patch, format it as "multipart/signed", not a text/plain message
  95that starts with '-----BEGIN PGP SIGNED MESSAGE-----'.  That is
  96not a text/plain, it's something else.
  97
  98Note that your maintainer does not necessarily read everything
  99on the git mailing list.  If your patch is for discussion first,
 100send it "To:" the mailing list, and optionally "cc:" him.  If it
 101is trivially correct or after the list reached a consensus, send
 102it "To:" the maintainer and optionally "cc:" the list.
 103
 104Also note that your maintainer does not actively involve himself in
 105maintaining what are in contrib/ hierarchy.  When you send fixes and
 106enhancements to them, do not forget to "cc: " the person who primarily
 107worked on that hierarchy in contrib/.
 108
 109
 110(4) Sign your work
 111
 112To improve tracking of who did what, we've borrowed the
 113"sign-off" procedure from the Linux kernel project on patches
 114that are being emailed around.  Although core GIT is a lot
 115smaller project it is a good discipline to follow it.
 116
 117The sign-off is a simple line at the end of the explanation for
 118the patch, which certifies that you wrote it or otherwise have
 119the right to pass it on as a open-source patch.  The rules are
 120pretty simple: if you can certify the below:
 121
 122        Developer's Certificate of Origin 1.1
 123
 124        By making a contribution to this project, I certify that:
 125
 126        (a) The contribution was created in whole or in part by me and I
 127            have the right to submit it under the open source license
 128            indicated in the file; or
 129
 130        (b) The contribution is based upon previous work that, to the best
 131            of my knowledge, is covered under an appropriate open source
 132            license and I have the right under that license to submit that
 133            work with modifications, whether created in whole or in part
 134            by me, under the same open source license (unless I am
 135            permitted to submit under a different license), as indicated
 136            in the file; or
 137
 138        (c) The contribution was provided directly to me by some other
 139            person who certified (a), (b) or (c) and I have not modified
 140            it.
 141
 142        (d) I understand and agree that this project and the contribution
 143            are public and that a record of the contribution (including all
 144            personal information I submit with it, including my sign-off) is
 145            maintained indefinitely and may be redistributed consistent with
 146            this project or the open source license(s) involved.
 147
 148then you just add a line saying
 149
 150        Signed-off-by: Random J Developer <random@developer.example.org>
 151
 152This line can be automatically added by git if you run the git-commit
 153command with the -s option.
 154
 155Some people also put extra tags at the end.  They'll just be ignored for
 156now, but you can do this to mark internal company procedures or just
 157point out some special detail about the sign-off.
 158
 159
 160------------------------------------------------
 161MUA specific hints
 162
 163Some of patches I receive or pick up from the list share common
 164patterns of breakage.  Please make sure your MUA is set up
 165properly not to corrupt whitespaces.  Here are two common ones
 166I have seen:
 167
 168* Empty context lines that do not have _any_ whitespace.
 169
 170* Non empty context lines that have one extra whitespace at the
 171  beginning.
 172
 173One test you could do yourself if your MUA is set up correctly is:
 174
 175* Send the patch to yourself, exactly the way you would, except
 176  To: and Cc: lines, which would not contain the list and
 177  maintainer address.
 178
 179* Save that patch to a file in UNIX mailbox format.  Call it say
 180  a.patch.
 181
 182* Try to apply to the tip of the "master" branch from the
 183  git.git public repository:
 184
 185    $ git fetch http://kernel.org/pub/scm/git/git.git master:test-apply
 186    $ git checkout test-apply
 187    $ git reset --hard
 188    $ git applymbox a.patch
 189
 190If it does not apply correctly, there can be various reasons.
 191
 192* Your patch itself does not apply cleanly.  That is _bad_ but
 193  does not have much to do with your MUA.  Please rebase the
 194  patch appropriately.
 195
 196* Your MUA corrupted your patch; applymbox would complain that
 197  the patch does not apply.  Look at .dotest/ subdirectory and
 198  see what 'patch' file contains and check for the common
 199  corruption patterns mentioned above.
 200
 201* While you are at it, check what are in 'info' and
 202  'final-commit' files as well.  If what is in 'final-commit' is
 203  not exactly what you would want to see in the commit log
 204  message, it is very likely that your maintainer would end up
 205  hand editing the log message when he applies your patch.
 206  Things like "Hi, this is my first patch.\n", if you really
 207  want to put in the patch e-mail, should come after the
 208  three-dash line that signals the end of the commit message.
 209
 210
 211Pine
 212----
 213
 214(Johannes Schindelin)
 215
 216I don't know how many people still use pine, but for those poor
 217souls it may be good to mention that the quell-flowed-text is
 218needed for recent versions.
 219
 220... the "no-strip-whitespace-before-send" option, too. AFAIK it
 221was introduced in 4.60.
 222
 223(Linus Torvalds)
 224
 225And 4.58 needs at least this.
 226
 227---
 228diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)
 229Author: Linus Torvalds <torvalds@g5.osdl.org>
 230Date:   Mon Aug 15 17:23:51 2005 -0700
 231
 232    Fix pine whitespace-corruption bug
 233
 234    There's no excuse for unconditionally removing whitespace from
 235    the pico buffers on close.
 236
 237diff --git a/pico/pico.c b/pico/pico.c
 238--- a/pico/pico.c
 239+++ b/pico/pico.c
 240@@ -219,7 +219,9 @@ PICO *pm;
 241            switch(pico_all_done){      /* prepare for/handle final events */
 242              case COMP_EXIT :          /* already confirmed */
 243                packheader();
 244+#if 0
 245                stripwhitespace();
 246+#endif
 247                c |= COMP_EXIT;
 248                break;
 249 
 250
 251(Daniel Barkalow)
 252
 253> A patch to SubmittingPatches, MUA specific help section for
 254> users of Pine 4.63 would be very much appreciated.
 255
 256Ah, it looks like a recent version changed the default behavior to do the
 257right thing, and inverted the sense of the configuration option. (Either
 258that or Gentoo did it.) So you need to set the
 259"no-strip-whitespace-before-send" option, unless the option you have is
 260"strip-whitespace-before-send", in which case you should avoid checking
 261it.
 262
 263
 264Thunderbird
 265-----------
 266
 267(A Large Angry SCM)
 268
 269Here are some hints on how to successfully submit patches inline using
 270Thunderbird.
 271
 272This recipe appears to work with the current [*1*] Thunderbird from Suse.
 273
 274The following Thunderbird extensions are needed:
 275        AboutConfig 0.5
 276                http://aboutconfig.mozdev.org/
 277        External Editor 0.7.2
 278                http://globs.org/articles.php?lng=en&pg=8
 279
 2801) Prepare the patch as a text file using your method of choice.
 281
 2822) Before opening a compose window, use Edit->Account Settings to
 283uncheck the "Compose messages in HTML format" setting in the
 284"Composition & Addressing" panel of the account to be used to send the
 285patch. [*2*]
 286
 2873) In the main Thunderbird window, _before_ you open the compose window
 288for the patch, use Tools->about:config to set the following to the
 289indicated values:
 290        mailnews.send_plaintext_flowed  => false
 291        mailnews.wraplength             => 0
 292
 2934) Open a compose window and click the external editor icon.
 294
 2955) In the external editor window, read in the patch file and exit the
 296editor normally.
 297
 2986) Back in the compose window: Add whatever other text you wish to the
 299message, complete the addressing and subject fields, and press send.
 300
 3017) Optionally, undo the about:config/account settings changes made in
 302steps 2 & 3.
 303
 304
 305[Footnotes]
 306*1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse
 3079.3 professional updates.
 308
 309*2* It may be possible to do this with about:config and the following
 310settings but I haven't tried, yet.
 311        mail.html_compose                       => false
 312        mail.identity.default.compose_html      => false
 313        mail.identity.id?.compose_html          => false
 314