Documentation / SubmittingPatcheson commit doc: status, remove leftover statement about '#' prefix (22d55ae)
   1Here are some guidelines for people who want to contribute their code
   2to this software.
   3
   4(0) Decide what to base your work on.
   5
   6In general, always base your work on the oldest branch that your
   7change is relevant to.
   8
   9 - A bugfix should be based on 'maint' in general. If the bug is not
  10   present in 'maint', base it on 'master'. For a bug that's not yet
  11   in 'master', find the topic that introduces the regression, and
  12   base your work on the tip of the topic.
  13
  14 - A new feature should be based on 'master' in general. If the new
  15   feature depends on a topic that is in 'pu', but not in 'master',
  16   base your work on the tip of that topic.
  17
  18 - Corrections and enhancements to a topic not yet in 'master' should
  19   be based on the tip of that topic. If the topic has not been merged
  20   to 'next', it's alright to add a note to squash minor corrections
  21   into the series.
  22
  23 - In the exceptional case that a new feature depends on several topics
  24   not in 'master', start working on 'next' or 'pu' privately and send
  25   out patches for discussion. Before the final merge, you may have to
  26   wait until some of the dependent topics graduate to 'master', and
  27   rebase your work.
  28
  29 - Some parts of the system have dedicated maintainers with their own
  30   repositories (see the section "Subsystems" below).  Changes to
  31   these parts should be based on their trees.
  32
  33To find the tip of a topic branch, run "git log --first-parent
  34master..pu" and look for the merge commit. The second parent of this
  35commit is the tip of the topic branch.
  36
  37(1) Make separate commits for logically separate changes.
  38
  39Unless your patch is really trivial, you should not be sending
  40out a patch that was generated between your working tree and
  41your commit head.  Instead, always make a commit with complete
  42commit message and generate a series of patches from your
  43repository.  It is a good discipline.
  44
  45Give an explanation for the change(s) that is detailed enough so
  46that people can judge if it is good thing to do, without reading
  47the actual patch text to determine how well the code does what
  48the explanation promises to do.
  49
  50If your description starts to get too long, that's a sign that you
  51probably need to split up your commit to finer grained pieces.
  52That being said, patches which plainly describe the things that
  53help reviewers check the patch, and future maintainers understand
  54the code, are the most beautiful patches.  Descriptions that summarise
  55the point in the subject well, and describe the motivation for the
  56change, the approach taken by the change, and if relevant how this
  57differs substantially from the prior version, are all good things
  58to have.
  59
  60Make sure that you have tests for the bug you are fixing.
  61
  62When adding a new feature, make sure that you have new tests to show
  63the feature triggers the new behaviour when it should, and to show the
  64feature does not trigger when it shouldn't.  Also make sure that the
  65test suite passes after your commit.  Do not forget to update the
  66documentation to describe the updated behaviour.
  67
  68Oh, another thing.  I am picky about whitespaces.  Make sure your
  69changes do not trigger errors with the sample pre-commit hook shipped
  70in templates/hooks--pre-commit.  To help ensure this does not happen,
  71run git diff --check on your changes before you commit.
  72
  73
  74(2) Describe your changes well.
  75
  76The first line of the commit message should be a short description (50
  77characters is the soft limit, see DISCUSSION in git-commit(1)), and
  78should skip the full stop.  It is also conventional in most cases to
  79prefix the first line with "area: " where the area is a filename or
  80identifier for the general area of the code being modified, e.g.
  81
  82  . archive: ustar header checksum is computed unsigned
  83  . git-cherry-pick.txt: clarify the use of revision range notation
  84
  85If in doubt which identifier to use, run "git log --no-merges" on the
  86files you are modifying to see the current conventions.
  87
  88The body should provide a meaningful commit message, which:
  89
  90  . explains the problem the change tries to solve, iow, what is wrong
  91    with the current code without the change.
  92
  93  . justifies the way the change solves the problem, iow, why the
  94    result with the change is better.
  95
  96  . alternate solutions considered but discarded, if any.
  97
  98Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
  99instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
 100to do frotz", as if you are giving orders to the codebase to change
 101its behaviour.  Try to make sure your explanation can be understood
 102without external resources. Instead of giving a URL to a mailing list
 103archive, summarize the relevant points of the discussion.
 104
 105
 106(3) Generate your patch using Git tools out of your commits.
 107
 108Git based diff tools generate unidiff which is the preferred format.
 109
 110You do not have to be afraid to use -M option to "git diff" or
 111"git format-patch", if your patch involves file renames.  The
 112receiving end can handle them just fine.
 113
 114Please make sure your patch does not add commented out debugging code,
 115or include any extra files which do not relate to what your patch
 116is trying to achieve. Make sure to review
 117your patch after generating it, to ensure accuracy.  Before
 118sending out, please make sure it cleanly applies to the "master"
 119branch head.  If you are preparing a work based on "next" branch,
 120that is fine, but please mark it as such.
 121
 122
 123(4) Sending your patches.
 124
 125People on the Git mailing list need to be able to read and
 126comment on the changes you are submitting.  It is important for
 127a developer to be able to "quote" your changes, using standard
 128e-mail tools, so that they may comment on specific portions of
 129your code.  For this reason, all patches should be submitted
 130"inline".  If your log message (including your name on the
 131Signed-off-by line) is not writable in ASCII, make sure that
 132you send off a message in the correct encoding.
 133
 134WARNING: Be wary of your MUAs word-wrap
 135corrupting your patch.  Do not cut-n-paste your patch; you can
 136lose tabs that way if you are not careful.
 137
 138It is a common convention to prefix your subject line with
 139[PATCH].  This lets people easily distinguish patches from other
 140e-mail discussions.  Use of additional markers after PATCH and
 141the closing bracket to mark the nature of the patch is also
 142encouraged.  E.g. [PATCH/RFC] is often used when the patch is
 143not ready to be applied but it is for discussion, [PATCH v2],
 144[PATCH v3] etc. are often seen when you are sending an update to
 145what you have previously sent.
 146
 147"git format-patch" command follows the best current practice to
 148format the body of an e-mail message.  At the beginning of the
 149patch should come your commit message, ending with the
 150Signed-off-by: lines, and a line that consists of three dashes,
 151followed by the diffstat information and the patch itself.  If
 152you are forwarding a patch from somebody else, optionally, at
 153the beginning of the e-mail message just before the commit
 154message starts, you can put a "From: " line to name that person.
 155
 156You often want to add additional explanation about the patch,
 157other than the commit message itself.  Place such "cover letter"
 158material between the three dash lines and the diffstat. Git-notes
 159can also be inserted using the `--notes` option.
 160
 161Do not attach the patch as a MIME attachment, compressed or not.
 162Do not let your e-mail client send quoted-printable.  Do not let
 163your e-mail client send format=flowed which would destroy
 164whitespaces in your patches. Many
 165popular e-mail applications will not always transmit a MIME
 166attachment as plain text, making it impossible to comment on
 167your code.  A MIME attachment also takes a bit more time to
 168process.  This does not decrease the likelihood of your
 169MIME-attached change being accepted, but it makes it more likely
 170that it will be postponed.
 171
 172Exception:  If your mailer is mangling patches then someone may ask
 173you to re-send them using MIME, that is OK.
 174
 175Do not PGP sign your patch, at least for now.  Most likely, your
 176maintainer or other people on the list would not have your PGP
 177key and would not bother obtaining it anyway.  Your patch is not
 178judged by who you are; a good patch from an unknown origin has a
 179far better chance of being accepted than a patch from a known,
 180respected origin that is done poorly or does incorrect things.
 181
 182If you really really really really want to do a PGP signed
 183patch, format it as "multipart/signed", not a text/plain message
 184that starts with '-----BEGIN PGP SIGNED MESSAGE-----'.  That is
 185not a text/plain, it's something else.
 186
 187Send your patch with "To:" set to the mailing list, with "cc:" listing
 188people who are involved in the area you are touching (the output from
 189"git blame $path" and "git shortlog --no-merges $path" would help to
 190identify them), to solicit comments and reviews.
 191
 192After the list reached a consensus that it is a good idea to apply the
 193patch, re-send it with "To:" set to the maintainer [*1*] and "cc:" the
 194list [*2*] for inclusion.
 195
 196Do not forget to add trailers such as "Acked-by:", "Reviewed-by:" and
 197"Tested-by:" lines as necessary to credit people who helped your
 198patch.
 199
 200    [Addresses]
 201     *1* The current maintainer: gitster@pobox.com
 202     *2* The mailing list: git@vger.kernel.org
 203
 204
 205(5) Sign your work
 206
 207To improve tracking of who did what, we've borrowed the
 208"sign-off" procedure from the Linux kernel project on patches
 209that are being emailed around.  Although core Git is a lot
 210smaller project it is a good discipline to follow it.
 211
 212The sign-off is a simple line at the end of the explanation for
 213the patch, which certifies that you wrote it or otherwise have
 214the right to pass it on as a open-source patch.  The rules are
 215pretty simple: if you can certify the below:
 216
 217        Developer's Certificate of Origin 1.1
 218
 219        By making a contribution to this project, I certify that:
 220
 221        (a) The contribution was created in whole or in part by me and I
 222            have the right to submit it under the open source license
 223            indicated in the file; or
 224
 225        (b) The contribution is based upon previous work that, to the best
 226            of my knowledge, is covered under an appropriate open source
 227            license and I have the right under that license to submit that
 228            work with modifications, whether created in whole or in part
 229            by me, under the same open source license (unless I am
 230            permitted to submit under a different license), as indicated
 231            in the file; or
 232
 233        (c) The contribution was provided directly to me by some other
 234            person who certified (a), (b) or (c) and I have not modified
 235            it.
 236
 237        (d) I understand and agree that this project and the contribution
 238            are public and that a record of the contribution (including all
 239            personal information I submit with it, including my sign-off) is
 240            maintained indefinitely and may be redistributed consistent with
 241            this project or the open source license(s) involved.
 242
 243then you just add a line saying
 244
 245        Signed-off-by: Random J Developer <random@developer.example.org>
 246
 247This line can be automatically added by Git if you run the git-commit
 248command with the -s option.
 249
 250Notice that you can place your own Signed-off-by: line when
 251forwarding somebody else's patch with the above rules for
 252D-C-O.  Indeed you are encouraged to do so.  Do not forget to
 253place an in-body "From: " line at the beginning to properly attribute
 254the change to its true author (see (2) above).
 255
 256Also notice that a real name is used in the Signed-off-by: line. Please
 257don't hide your real name.
 258
 259If you like, you can put extra tags at the end:
 260
 2611. "Reported-by:" is used to credit someone who found the bug that
 262   the patch attempts to fix.
 2632. "Acked-by:" says that the person who is more familiar with the area
 264   the patch attempts to modify liked the patch.
 2653. "Reviewed-by:", unlike the other tags, can only be offered by the
 266   reviewer and means that she is completely satisfied that the patch
 267   is ready for application.  It is usually offered only after a
 268   detailed review.
 2694. "Tested-by:" is used to indicate that the person applied the patch
 270   and found it to have the desired effect.
 271
 272You can also create your own tag or use one that's in common usage
 273such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
 274
 275------------------------------------------------
 276Subsystems with dedicated maintainers
 277
 278Some parts of the system have dedicated maintainers with their own
 279repositories.
 280
 281 - git-gui/ comes from git-gui project, maintained by Pat Thoyts:
 282
 283        git://repo.or.cz/git-gui.git
 284
 285 - gitk-git/ comes from Paul Mackerras's gitk project:
 286
 287        git://ozlabs.org/~paulus/gitk
 288
 289 - po/ comes from the localization coordinator, Jiang Xin:
 290
 291        https://github.com/git-l10n/git-po/
 292
 293Patches to these parts should be based on their trees.
 294
 295------------------------------------------------
 296An ideal patch flow
 297
 298Here is an ideal patch flow for this project the current maintainer
 299suggests to the contributors:
 300
 301 (0) You come up with an itch.  You code it up.
 302
 303 (1) Send it to the list and cc people who may need to know about
 304     the change.
 305
 306     The people who may need to know are the ones whose code you
 307     are butchering.  These people happen to be the ones who are
 308     most likely to be knowledgeable enough to help you, but
 309     they have no obligation to help you (i.e. you ask for help,
 310     don't demand).  "git log -p -- $area_you_are_modifying" would
 311     help you find out who they are.
 312
 313 (2) You get comments and suggestions for improvements.  You may
 314     even get them in a "on top of your change" patch form.
 315
 316 (3) Polish, refine, and re-send to the list and the people who
 317     spend their time to improve your patch.  Go back to step (2).
 318
 319 (4) The list forms consensus that the last round of your patch is
 320     good.  Send it to the list and cc the maintainer.
 321
 322 (5) A topic branch is created with the patch and is merged to 'next',
 323     and cooked further and eventually graduates to 'master'.
 324
 325In any time between the (2)-(3) cycle, the maintainer may pick it up
 326from the list and queue it to 'pu', in order to make it easier for
 327people play with it without having to pick up and apply the patch to
 328their trees themselves.
 329
 330------------------------------------------------
 331Know the status of your patch after submission
 332
 333* You can use Git itself to find out when your patch is merged in
 334  master. 'git pull --rebase' will automatically skip already-applied
 335  patches, and will let you know. This works only if you rebase on top
 336  of the branch in which your patch has been merged (i.e. it will not
 337  tell you if your patch is merged in pu if you rebase on top of
 338  master).
 339
 340* Read the Git mailing list, the maintainer regularly posts messages
 341  entitled "What's cooking in git.git" and "What's in git.git" giving
 342  the status of various proposed changes.
 343
 344------------------------------------------------
 345MUA specific hints
 346
 347Some of patches I receive or pick up from the list share common
 348patterns of breakage.  Please make sure your MUA is set up
 349properly not to corrupt whitespaces.
 350
 351See the DISCUSSION section of git-format-patch(1) for hints on
 352checking your patch by mailing it to yourself and applying with
 353git-am(1).
 354
 355While you are at it, check the resulting commit log message from
 356a trial run of applying the patch.  If what is in the resulting
 357commit is not exactly what you would want to see, it is very
 358likely that your maintainer would end up hand editing the log
 359message when he applies your patch.  Things like "Hi, this is my
 360first patch.\n", if you really want to put in the patch e-mail,
 361should come after the three-dash line that signals the end of the
 362commit message.
 363
 364
 365Pine
 366----
 367
 368(Johannes Schindelin)
 369
 370I don't know how many people still use pine, but for those poor
 371souls it may be good to mention that the quell-flowed-text is
 372needed for recent versions.
 373
 374... the "no-strip-whitespace-before-send" option, too. AFAIK it
 375was introduced in 4.60.
 376
 377(Linus Torvalds)
 378
 379And 4.58 needs at least this.
 380
 381---
 382diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)
 383Author: Linus Torvalds <torvalds@g5.osdl.org>
 384Date:   Mon Aug 15 17:23:51 2005 -0700
 385
 386    Fix pine whitespace-corruption bug
 387
 388    There's no excuse for unconditionally removing whitespace from
 389    the pico buffers on close.
 390
 391diff --git a/pico/pico.c b/pico/pico.c
 392--- a/pico/pico.c
 393+++ b/pico/pico.c
 394@@ -219,7 +219,9 @@ PICO *pm;
 395            switch(pico_all_done){      /* prepare for/handle final events */
 396              case COMP_EXIT :          /* already confirmed */
 397                packheader();
 398+#if 0
 399                stripwhitespace();
 400+#endif
 401                c |= COMP_EXIT;
 402                break;
 403
 404
 405(Daniel Barkalow)
 406
 407> A patch to SubmittingPatches, MUA specific help section for
 408> users of Pine 4.63 would be very much appreciated.
 409
 410Ah, it looks like a recent version changed the default behavior to do the
 411right thing, and inverted the sense of the configuration option. (Either
 412that or Gentoo did it.) So you need to set the
 413"no-strip-whitespace-before-send" option, unless the option you have is
 414"strip-whitespace-before-send", in which case you should avoid checking
 415it.
 416
 417
 418Thunderbird, KMail, GMail
 419-------------------------
 420
 421See the MUA-SPECIFIC HINTS section of git-format-patch(1).
 422
 423Gnus
 424----
 425
 426'|' in the *Summary* buffer can be used to pipe the current
 427message to an external program, and this is a handy way to drive
 428"git am".  However, if the message is MIME encoded, what is
 429piped into the program is the representation you see in your
 430*Article* buffer after unwrapping MIME.  This is often not what
 431you would want for two reasons.  It tends to screw up non ASCII
 432characters (most notably in people's names), and also
 433whitespaces (fatal in patches).  Running 'C-u g' to display the
 434message in raw form before using '|' to run the pipe can work
 435this problem around.