mirror of
https://github.com/git/git
synced 2024-08-27 11:39:22 +00:00
Merge branch 'jc/submittingpatches' into maint
* jc/submittingpatches: SubmittingPatches: give list and maintainer addresses SubmittingPatches: remove overlong checklist SubmittingPatches: mention subsystems with dedicated repositories SubmittingPatches: who am I and who cares?
This commit is contained in:
commit
02cb8da20d
|
@ -1,73 +1,5 @@
|
|||
Checklist (and a short version for the impatient):
|
||||
|
||||
Commits:
|
||||
|
||||
- make commits of logical units
|
||||
- check for unnecessary whitespace with "git diff --check"
|
||||
before committing
|
||||
- do not check in commented out code or unneeded files
|
||||
- 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.
|
||||
. 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 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.
|
||||
- add a "Signed-off-by: Your Name <you@example.com>" line to the
|
||||
commit message (or just use the option "-s" when committing)
|
||||
to confirm that you agree to the Developer's Certificate of Origin
|
||||
- make sure that you have tests for the bug you are fixing
|
||||
- make sure that the test suite passes after your commit
|
||||
|
||||
Patch:
|
||||
|
||||
- use "git format-patch -M" to create the patch
|
||||
- do not PGP sign your patch
|
||||
- do not attach your patch, but read in the mail
|
||||
body, unless you cannot teach your mailer to
|
||||
leave the formatting of the patch alone.
|
||||
- be careful doing cut & paste into your mailer, not to
|
||||
corrupt whitespaces.
|
||||
- provide additional information (which is unsuitable for
|
||||
the commit message) between the "---" and the diffstat
|
||||
- if you change, add, or remove a command line option or
|
||||
make some other user interface change, the associated
|
||||
documentation should be updated as well.
|
||||
- if your name is not writable in ASCII, make sure that
|
||||
you send off a message in the correct encoding.
|
||||
- send the patch to the list (git@vger.kernel.org) and the
|
||||
maintainer (gitster@pobox.com) if (and only if) the patch
|
||||
is ready for inclusion. If you use git-send-email(1),
|
||||
please test it first by sending email to yourself.
|
||||
- see below for instructions specific to your mailer
|
||||
|
||||
Long version:
|
||||
|
||||
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.
|
||||
|
||||
But the patch submission requirements are a lot more relaxed
|
||||
here on the technical/contents front, because the core GIT is
|
||||
thousand times smaller ;-). So here is only the relevant bits.
|
||||
Here are some guidelines for people who want to contribute their code
|
||||
to this software.
|
||||
|
||||
(0) Decide what to base your work on.
|
||||
|
||||
|
@ -94,6 +26,10 @@ change is relevant 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.
|
||||
|
@ -121,13 +57,53 @@ 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.
|
||||
|
||||
Oh, another thing. I am 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) Generate your patch using git tools out of your commits.
|
||||
(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.
|
||||
|
||||
. 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.
|
||||
|
||||
|
@ -135,22 +111,27 @@ 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. 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 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 submitted
|
||||
"inline". WARNING: Be wary of your MUAs word-wrap
|
||||
"inline". 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.
|
||||
|
||||
|
@ -203,19 +184,25 @@ patch, format it as "multipart/signed", not a text/plain message
|
|||
that starts with '-----BEGIN PGP SIGNED MESSAGE-----'. That is
|
||||
not a text/plain, it's something else.
|
||||
|
||||
Unless your patch is a very trivial and an obviously correct one,
|
||||
first send it with "To:" set to the mailing list, with "cc:" listing
|
||||
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 and optionally "cc:" the list for
|
||||
inclusion. Do not forget to add trailers such as "Acked-by:",
|
||||
"Reviewed-by:" and "Tested-by:" after your "Signed-off-by:" line as
|
||||
necessary.
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
|
||||
(4) Sign your work
|
||||
(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
|
||||
|
@ -285,6 +272,26 @@ If you like, you can put extra tags at the end:
|
|||
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:".
|
||||
|
||||
------------------------------------------------
|
||||
Subsystems with dedicated maintainers
|
||||
|
||||
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/
|
||||
|
||||
Patches to these parts should be based on their trees.
|
||||
|
||||
------------------------------------------------
|
||||
An ideal patch flow
|
||||
|
||||
|
|
Loading…
Reference in a new issue