-I started reading over the SubmittingPatches document for Linux
-kernel, primarily because I wanted to have a document similar to
-it for the core GIT to make sure people understand what they are
-doing when they write "Signed-off-by" line.
+Here are some guidelines for people who want to contribute their code
+to this software.
-But the patch submission requirements are a lot more relaxed
-here, because the core GIT is thousand times smaller ;-). So
-here is only the relevant bits.
+(0) Decide what to base your work on.
+In general, always base your work on the oldest branch that your
+change is relevant to.
+
+ - A bugfix should be based on 'maint' in general. If the bug is not
+ present in 'maint', base it on 'master'. For a bug that's not yet
+ in 'master', find the topic that introduces the regression, and
+ base your work on the tip of the topic.
+
+ - A new feature should be based on 'master' in general. If the new
+ feature depends on a topic that is in 'pu', but not in 'master',
+ base your work on the tip of that topic.
+
+ - Corrections and enhancements to a topic not yet in 'master' should
+ be based on the tip of that topic. If the topic has not been merged
+ to 'next', it's alright to add a note to squash minor corrections
+ into the series.
+
+ - In the exceptional case that a new feature depends on several topics
+ not in 'master', start working on 'next' or 'pu' privately and send
+ out patches for discussion. Before the final merge, you may have to
+ wait until some of the dependent topics graduate to 'master', and
+ rebase your work.
+
+ - Some parts of the system have dedicated maintainers with their own
+ repositories (see the section "Subsystems" below). Changes to
+ these parts should be based on their trees.
+
+To find the tip of a topic branch, run "git log --first-parent
+master..pu" and look for the merge commit. The second parent of this
+commit is the tip of the topic branch.
(1) Make separate commits for logically separate changes.
commit message and generate a series of patches from your
repository. It is a good discipline.
-Describe the technical detail of the change(s).
+Give an explanation for the change(s) that is detailed enough so
+that people can judge if it is good thing to do, without reading
+the actual patch text to determine how well the code does what
+the explanation promises to do.
-If your description starts to get long, that's a sign that you
+If your description starts to get too long, that's a sign that you
probably need to split up your commit to finer grained pieces.
+That being said, patches which plainly describe the things that
+help reviewers check the patch, and future maintainers understand
+the code, are the most beautiful patches. Descriptions that summarise
+the point in the subject well, and describe the motivation for the
+change, the approach taken by the change, and if relevant how this
+differs substantially from the prior version, are all good things
+to have.
+
+Make sure that you have tests for the bug you are fixing.
+
+When adding a new feature, make sure that you have new tests to show
+the feature triggers the new behaviour when it should, and to show the
+feature does not trigger when it shouldn't. Also make sure that the
+test suite passes after your commit. Do not forget to update the
+documentation to describe the updated behaviour.
+
+Speaking of the documentation, it is currently a liberal mixture of US
+and UK English norms for spelling and grammar, which is somewhat
+unfortunate. A huge patch that touches the files all over the place
+only to correct the inconsistency is not welcome, though. Potential
+clashes with other changes that can result from such a patch are not
+worth it. We prefer to gradually reconcile the inconsistencies in
+favor of US English, with small and easily digestible patches, as a
+side effect of doing some other real work in the vicinity (e.g.
+rewriting a paragraph for clarity, while turning en_UK spelling to
+en_US). Obvious typographical fixes are much more welcomed ("teh ->
+"the"), preferably submitted as independent patches separate from
+other documentation changes.
+
+Oh, another thing. We are picky about whitespaces. Make sure your
+changes do not trigger errors with the sample pre-commit hook shipped
+in templates/hooks--pre-commit. To help ensure this does not happen,
+run git diff --check on your changes before you commit.
+
+
+(2) Describe your changes well.
+
+The first line of the commit message should be a short description (50
+characters is the soft limit, see DISCUSSION in git-commit(1)), and
+should skip the full stop. It is also conventional in most cases to
+prefix the first line with "area: " where the area is a filename or
+identifier for the general area of the code being modified, e.g.
+
+ . archive: ustar header checksum is computed unsigned
+ . git-cherry-pick.txt: clarify the use of revision range notation
+
+If in doubt which identifier to use, run "git log --no-merges" on the
+files you are modifying to see the current conventions.
+
+The body should provide a meaningful commit message, which:
+ . explains the problem the change tries to solve, iow, what is wrong
+ with the current code without the change.
-(2) Generate your patch using git/cogito out of your commits.
+ . justifies the way the change solves the problem, iow, why the
+ result with the change is better.
+
+ . alternate solutions considered but discarded, if any.
+
+Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
+instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
+to do frotz", as if you are giving orders to the codebase to change
+its behaviour. Try to make sure your explanation can be understood
+without external resources. Instead of giving a URL to a mailing list
+archive, summarize the relevant points of the discussion.
+
+
+(3) Generate your patch using Git tools out of your commits.
+
+Git based diff tools generate unidiff which is the preferred format.
-git diff tools generate unidiff which is the preferred format.
You do not have to be afraid to use -M option to "git diff" or
"git format-patch", if your patch involves file renames. The
receiving end can handle them just fine.
-Please make sure your patch does not include any extra files
-which do not belong in a patch submission. Make sure to review
+Please make sure your patch does not add commented out debugging code,
+or include any extra files which do not relate to what your patch
+is trying to achieve. Make sure to review
your patch after generating it, to ensure accuracy. Before
sending out, please make sure it cleanly applies to the "master"
-branch head.
+branch head. If you are preparing a work based on "next" branch,
+that is fine, but please mark it as such.
-(3) Sending your patches.
+(4) Sending your patches.
-People on the git mailing list needs to be able to read and
+People on the Git mailing list need to be able to read and
comment on the changes you are submitting. It is important for
a developer to be able to "quote" your changes, using standard
e-mail tools, so that they may comment on specific portions of
-your code. For this reason, all patches should be submitting
-e-mail "inline". WARNING: Be wary of your MUAs word-wrap
-corrupting your patch. Do not cut-n-paste your patch.
+your code. For this reason, each patch should be submitted
+"inline" in a separate message.
+
+Multiple related patches should be grouped into their own e-mail
+thread to help readers find all parts of the series. To that end,
+send them as replies to either an additional "cover letter" message
+(see below), the first patch, or the respective preceding patch.
+
+If your log message (including your name on the
+Signed-off-by line) is not writable in ASCII, make sure that
+you send off a message in the correct encoding.
+
+WARNING: Be wary of your MUAs word-wrap
+corrupting your patch. Do not cut-n-paste your patch; you can
+lose tabs that way if you are not careful.
-It is common convention to prefix your subject line with
+It is a common convention to prefix your subject line with
[PATCH]. This lets people easily distinguish patches from other
-e-mail discussions.
+e-mail discussions. Use of additional markers after PATCH and
+the closing bracket to mark the nature of the patch is also
+encouraged. E.g. [PATCH/RFC] is often used when the patch is
+not ready to be applied but it is for discussion, [PATCH v2],
+[PATCH v3] etc. are often seen when you are sending an update to
+what you have previously sent.
"git format-patch" command follows the best current practice to
format the body of an e-mail message. At the beginning of the
You often want to add additional explanation about the patch,
other than the commit message itself. Place such "cover letter"
-material between the three dash lines and the diffstat.
+material between the three dash lines and the diffstat. Git-notes
+can also be inserted using the `--notes` option.
Do not attach the patch as a MIME attachment, compressed or not.
-Do not let your e-mail client send quoted-printable. Many
+Do not let your e-mail client send quoted-printable. Do not let
+your e-mail client send format=flowed which would destroy
+whitespaces in your patches. Many
popular e-mail applications will not always transmit a MIME
attachment as plain text, making it impossible to comment on
your code. A MIME attachment also takes a bit more time to
that starts with '-----BEGIN PGP SIGNED MESSAGE-----'. That is
not a text/plain, it's something else.
-Note that your maintainer does not necessarily read everything
-on the git mailing list. If your patch is for discussion first,
-send it "To:" the mailing list, and optionally "cc:" him. If it
-is trivially correct or after the list reached a consensus, send
-it "To:" the maintainer and optionally "cc:" the list.
+Send your patch with "To:" set to the mailing list, with "cc:" listing
+people who are involved in the area you are touching (the output from
+"git blame $path" and "git shortlog --no-merges $path" would help to
+identify them), to solicit comments and reviews.
+After the list reached a consensus that it is a good idea to apply the
+patch, re-send it with "To:" set to the maintainer [*1*] and "cc:" the
+list [*2*] for inclusion.
-(6) Sign your work
+Do not forget to add trailers such as "Acked-by:", "Reviewed-by:" and
+"Tested-by:" lines as necessary to credit people who helped your
+patch.
+
+ [Addresses]
+ *1* The current maintainer: gitster@pobox.com
+ *2* The mailing list: git@vger.kernel.org
+
+
+(5) Sign your work
To improve tracking of who did what, we've borrowed the
"sign-off" procedure from the Linux kernel project on patches
-that are being emailed around. Although core GIT is a lot
+that are being emailed around. Although core Git is a lot
smaller project it is a good discipline to follow it.
The sign-off is a simple line at the end of the explanation for
Signed-off-by: Random J Developer <random@developer.example.org>
-Some people also put extra tags at the end. They'll just be ignored for
-now, but you can do this to mark internal company procedures or just
-point out some special detail about the sign-off.
+This line can be automatically added by Git if you run the git-commit
+command with the -s option.
+
+Notice that you can place your own Signed-off-by: line when
+forwarding somebody else's patch with the above rules for
+D-C-O. Indeed you are encouraged to do so. Do not forget to
+place an in-body "From: " line at the beginning to properly attribute
+the change to its true author (see (2) above).
+Also notice that a real name is used in the Signed-off-by: line. Please
+don't hide your real name.
+
+If you like, you can put extra tags at the end:
+
+1. "Reported-by:" is used to credit someone who found the bug that
+ the patch attempts to fix.
+2. "Acked-by:" says that the person who is more familiar with the area
+ the patch attempts to modify liked the patch.
+3. "Reviewed-by:", unlike the other tags, can only be offered by the
+ reviewer and means that she is completely satisfied that the patch
+ is ready for application. It is usually offered only after a
+ detailed review.
+4. "Tested-by:" is used to indicate that the person applied the patch
+ and found it to have the desired effect.
+
+You can also create your own tag or use one that's in common usage
+such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
------------------------------------------------
-MUA specific hints
+Subsystems with dedicated maintainers
-Some of patches I receive or pick up from the list share common
-patterns of breakage. Please make sure your MUA is set up
-properly not to corrupt whitespaces. Here are two common ones
-I have seen:
+Some parts of the system have dedicated maintainers with their own
+repositories.
+
+ - git-gui/ comes from git-gui project, maintained by Pat Thoyts:
+
+ git://repo.or.cz/git-gui.git
+
+ - gitk-git/ comes from Paul Mackerras's gitk project:
+
+ git://ozlabs.org/~paulus/gitk
+
+ - po/ comes from the localization coordinator, Jiang Xin:
+
+ https://github.com/git-l10n/git-po/
-* Empty context lines that do not have _any_ whitespace.
+Patches to these parts should be based on their trees.
-* Non empty context lines that have one extra whitespace at the
- beginning.
+------------------------------------------------
+An ideal patch flow
+
+Here is an ideal patch flow for this project the current maintainer
+suggests to the contributors:
+
+ (0) You come up with an itch. You code it up.
+
+ (1) Send it to the list and cc people who may need to know about
+ the change.
-One test you could do yourself if your MUA is set up correctly is:
+ The people who may need to know are the ones whose code you
+ are butchering. These people happen to be the ones who are
+ most likely to be knowledgeable enough to help you, but
+ they have no obligation to help you (i.e. you ask for help,
+ don't demand). "git log -p -- $area_you_are_modifying" would
+ help you find out who they are.
-* Send the patch to yourself, exactly the way you would, except
- To: and Cc: lines, which would not contain the list and
- maintainer address.
+ (2) You get comments and suggestions for improvements. You may
+ even get them in a "on top of your change" patch form.
-* Save that patch to a file in UNIX mailbox format. Call it say
- a.patch.
+ (3) Polish, refine, and re-send to the list and the people who
+ spend their time to improve your patch. Go back to step (2).
-* Try to apply to the tip of the "master" branch from the
- git.git public repository:
+ (4) The list forms consensus that the last round of your patch is
+ good. Send it to the list and cc the maintainer.
- $ git fetch http://kernel.org/pub/scm/git/git.git master:test-apply
- $ git checkout test-apply
- $ git reset --hard
- $ git applymbox a.patch
+ (5) A topic branch is created with the patch and is merged to 'next',
+ and cooked further and eventually graduates to 'master'.
-If it does not apply correctly, there can be various reasons.
+In any time between the (2)-(3) cycle, the maintainer may pick it up
+from the list and queue it to 'pu', in order to make it easier for
+people play with it without having to pick up and apply the patch to
+their trees themselves.
-* Your patch itself does not apply cleanly. That is _bad_ but
- does not have much to do with your MUA. Please rebase the
- patch appropriately.
+------------------------------------------------
+Know the status of your patch after submission
-* Your MUA corrupted your patch; applymbox would complain that
- the patch does not apply. Look at .dotest/ subdirectory and
- see what 'patch' file contains and check for the common
- corruption patterns mentioned above.
+* You can use Git itself to find out when your patch is merged in
+ master. 'git pull --rebase' will automatically skip already-applied
+ patches, and will let you know. This works only if you rebase on top
+ of the branch in which your patch has been merged (i.e. it will not
+ tell you if your patch is merged in pu if you rebase on top of
+ master).
-* While you are at it, check what are in 'info' and
- 'final-commit' files as well. If what is in 'final-commit' is
- not exactly what you would want to see in the commit log
- message, it is very likely that your maintainer would end up
- hand editing the log message when he applies your patch.
- Things like "Hi, this is my first patch.\n", if you really
- want to put in the patch e-mail, should come after the
- three-dash line that signals the end of the commit message.
+* Read the Git mailing list, the maintainer regularly posts messages
+ entitled "What's cooking in git.git" and "What's in git.git" giving
+ the status of various proposed changes.
+
+------------------------------------------------
+MUA specific hints
+
+Some of patches I receive or pick up from the list share common
+patterns of breakage. Please make sure your MUA is set up
+properly not to corrupt whitespaces.
+
+See the DISCUSSION section of git-format-patch(1) for hints on
+checking your patch by mailing it to yourself and applying with
+git-am(1).
+
+While you are at it, check the resulting commit log message from
+a trial run of applying the patch. If what is in the resulting
+commit is not exactly what you would want to see, it is very
+likely that your maintainer would end up hand editing the log
+message when he applies your patch. Things like "Hi, this is my
+first patch.\n", if you really want to put in the patch e-mail,
+should come after the three-dash line that signals the end of the
+commit message.
Pine
--- a/pico/pico.c
+++ b/pico/pico.c
@@ -219,7 +219,9 @@ PICO *pm;
- switch(pico_all_done){ /* prepare for/handle final events */
- case COMP_EXIT : /* already confirmed */
- packheader();
+ switch(pico_all_done){ /* prepare for/handle final events */
+ case COMP_EXIT : /* already confirmed */
+ packheader();
+#if 0
- stripwhitespace();
+ stripwhitespace();
+#endif
- c |= COMP_EXIT;
- break;
-
-
-
-Thunderbird
------------
-
-(A Large Angry SCM)
+ c |= COMP_EXIT;
+ break;
-Here are some hints on how to successfully submit patches inline using
-Thunderbird. [*3*]
-This recipe appears to work with the current [*1*] Thunderbird from Suse.
+(Daniel Barkalow)
-The following Thunderbird extensions are needed:
- AboutConfig 0.5
- http://aboutconfig.mozdev.org/
- External Editor 0.5.4
- http://extensionroom.mozdev.org/more-info/exteditor
+> A patch to SubmittingPatches, MUA specific help section for
+> users of Pine 4.63 would be very much appreciated.
-1) Prepare the patch as a text file using your method of choice.
+Ah, it looks like a recent version changed the default behavior to do the
+right thing, and inverted the sense of the configuration option. (Either
+that or Gentoo did it.) So you need to set the
+"no-strip-whitespace-before-send" option, unless the option you have is
+"strip-whitespace-before-send", in which case you should avoid checking
+it.
-2) Before opening a compose window, use Edit->Account Settings to
-uncheck the "Compose messages in HTML format" setting in the
-"Composition & Addressing" panel of the account to be used to send the
-patch. [*2*]
-3) In the main Thunderbird window, _before_ you open the compose window
-for the patch, use Tools->about:config to set the following to the
-indicated values:
- mailnews.send_plaintext_flowed => false
- mailnews.wraplength => 999
+Thunderbird, KMail, GMail
+-------------------------
-4) Open a compose window and click the external editor icon.
+See the MUA-SPECIFIC HINTS section of git-format-patch(1).
-5) In the external editor window, read in the patch file and exit the
-editor normally.
-
-6) Back in the compose window: Add whatever other text you wish to the
-message, complete the addressing and subject fields, and press send.
-
-7) Optionally, undo the about:config/account settings changes made in
-steps 2 & 3.
-
-
-[Footnotes]
-*1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse
-9.3 professional updates.
-
-*2* It may be possible to do this with about:config and the following
-settings but I haven't tried, yet.
- mail.html_compose => false
- mail.identity.default.compose_html => false
- mail.identity.id?.compose_html => false
-
-*3* Even after following these hints, Thunderbird will still trim
-trailing whitespace from each line. I currently have no work around for
-for this issue.
+Gnus
+----
+'|' in the *Summary* buffer can be used to pipe the current
+message to an external program, and this is a handy way to drive
+"git am". However, if the message is MIME encoded, what is
+piped into the program is the representation you see in your
+*Article* buffer after unwrapping MIME. This is often not what
+you would want for two reasons. It tends to screw up non ASCII
+characters (most notably in people's names), and also
+whitespaces (fatal in patches). Running 'C-u g' to display the
+message in raw form before using '|' to run the pipe can work
+this problem around.