mirror of
https://github.com/git/git
synced 2024-10-02 14:45:21 +00:00
Merge branch 'la/doc-use-of-contacts-when-contributing'
Advertise "git contacts", a tool for newcomers to find people to ask review for their patches, a bit more in our developer documentation. * la/doc-use-of-contacts-when-contributing: SubmittingPatches: demonstrate using git-contacts with git-send-email SubmittingPatches: add heading for format-patch and send-email SubmittingPatches: dedupe discussion of security patches SubmittingPatches: discuss reviewers first SubmittingPatches: quote commands SubmittingPatches: mention GitGitGadget SubmittingPatches: clarify 'git-contacts' location MyFirstContribution: mention contrib/contacts/git-contacts
This commit is contained in:
commit
07410bb4e8
|
@ -1116,6 +1116,15 @@ $ git send-email --to=target@example.com psuh/*.patch
|
||||||
NOTE: Check `git help send-email` for some other options which you may find
|
NOTE: Check `git help send-email` for some other options which you may find
|
||||||
valuable, such as changing the Reply-to address or adding more CC and BCC lines.
|
valuable, such as changing the Reply-to address or adding more CC and BCC lines.
|
||||||
|
|
||||||
|
:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
|
||||||
|
not part of the core `git` binary and must be called directly. Clone the Git +
|
||||||
|
codebase and run `perl contrib/contacts/git-contacts`.]
|
||||||
|
|
||||||
|
NOTE: If you're not sure whom to CC, running `contrib/contacts/git-contacts` can
|
||||||
|
list potential reviewers. In addition, you can do `git send-email
|
||||||
|
--cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch`{contrib-scripts} to
|
||||||
|
automatically pass this list of emails to `send-email`.
|
||||||
|
|
||||||
NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
|
NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
|
||||||
please don't send your patchset from the tutorial to the real mailing list! For
|
please don't send your patchset from the tutorial to the real mailing list! For
|
||||||
now, you can send it to yourself, to make sure you understand how it will look.
|
now, you can send it to yourself, to make sure you understand how it will look.
|
||||||
|
|
|
@ -397,17 +397,57 @@ letter.
|
||||||
[[send-patches]]
|
[[send-patches]]
|
||||||
=== Sending your patches.
|
=== Sending your patches.
|
||||||
|
|
||||||
|
==== Choosing your reviewers
|
||||||
|
|
||||||
:security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
|
:security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
|
||||||
|
|
||||||
Before sending any patches, please note that patches that may be
|
NOTE: Patches that may be
|
||||||
security relevant should be submitted privately to the Git Security
|
security relevant should be submitted privately to the Git Security
|
||||||
mailing list{security-ml}, instead of the public mailing list.
|
mailing list{security-ml}, instead of the public mailing list.
|
||||||
|
|
||||||
Learn to use format-patch and send-email if possible. These commands
|
:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
|
||||||
|
not part of the core `git` binary and must be called directly. Clone the Git +
|
||||||
|
codebase and run `perl contrib/contacts/git-contacts`.]
|
||||||
|
|
||||||
|
Send your patch with "To:" set to the mailing list, with "cc:" listing
|
||||||
|
people who are involved in the area you are touching (the `git-contacts`
|
||||||
|
script in `contrib/contacts/`{contrib-scripts} can help to
|
||||||
|
identify them), to solicit comments and reviews. Also, when you made
|
||||||
|
trial merges of your topic to `next` and `seen`, you may have noticed
|
||||||
|
work by others conflicting with your changes. There is a good possibility
|
||||||
|
that these people may know the area you are touching well.
|
||||||
|
|
||||||
|
If you are using `send-email`, you can feed it the output of `git-contacts` like
|
||||||
|
this:
|
||||||
|
|
||||||
|
....
|
||||||
|
git send-email --cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch
|
||||||
|
....
|
||||||
|
|
||||||
|
:current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
|
||||||
|
:git-ml: footnote:[The mailing list: git@vger.kernel.org]
|
||||||
|
|
||||||
|
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{current-maintainer}
|
||||||
|
and "cc:" the list{git-ml} for inclusion. This is especially relevant
|
||||||
|
when the maintainer did not heavily participate in the discussion and
|
||||||
|
instead left the review to trusted others.
|
||||||
|
|
||||||
|
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, and "cc:" them when sending such a final version for inclusion.
|
||||||
|
|
||||||
|
==== `format-patch` and `send-email`
|
||||||
|
|
||||||
|
Learn to use `format-patch` and `send-email` if possible. These commands
|
||||||
are optimized for the workflow of sending patches, avoiding many ways
|
are optimized for the workflow of sending patches, avoiding many ways
|
||||||
your existing e-mail client (often optimized for "multipart/*" MIME
|
your existing e-mail client (often optimized for "multipart/*" MIME
|
||||||
type e-mails) might render your patches unusable.
|
type e-mails) might render your patches unusable.
|
||||||
|
|
||||||
|
NOTE: Here we outline the procedure using `format-patch` and
|
||||||
|
`send-email`, but you can instead use GitGitGadget to send in your
|
||||||
|
patches (see link:MyFirstContribution.html[MyFirstContribution]).
|
||||||
|
|
||||||
People on the Git mailing list need 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
|
comment on the changes you are submitting. It is important for
|
||||||
a developer to be able to "quote" your changes, using standard
|
a developer to be able to "quote" your changes, using standard
|
||||||
|
@ -498,34 +538,6 @@ patch, format it as "multipart/signed", not a text/plain message
|
||||||
that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is
|
that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is
|
||||||
not a text/plain, it's something else.
|
not a text/plain, it's something else.
|
||||||
|
|
||||||
:security-ml-ref: footnoteref:[security-ml]
|
|
||||||
|
|
||||||
As mentioned at the beginning of the section, patches that may be
|
|
||||||
security relevant should not be submitted to the public mailing list
|
|
||||||
mentioned below, but should instead be sent privately to the Git
|
|
||||||
Security mailing list{security-ml-ref}.
|
|
||||||
|
|
||||||
Send your patch with "To:" set to the mailing list, with "cc:" listing
|
|
||||||
people who are involved in the area you are touching (the `git
|
|
||||||
contacts` command in `contrib/contacts/` can help to
|
|
||||||
identify them), to solicit comments and reviews. Also, when you made
|
|
||||||
trial merges of your topic to `next` and `seen`, you may have noticed
|
|
||||||
work by others conflicting with your changes. There is a good possibility
|
|
||||||
that these people may know the area you are touching well.
|
|
||||||
|
|
||||||
:current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
|
|
||||||
:git-ml: footnote:[The mailing list: git@vger.kernel.org]
|
|
||||||
|
|
||||||
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{current-maintainer}
|
|
||||||
and "cc:" the list{git-ml} for inclusion. This is especially relevant
|
|
||||||
when the maintainer did not heavily participate in the discussion and
|
|
||||||
instead left the review to trusted others.
|
|
||||||
|
|
||||||
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, and "cc:" them when sending such a final version for inclusion.
|
|
||||||
|
|
||||||
== Subsystems with dedicated maintainers
|
== Subsystems with dedicated maintainers
|
||||||
|
|
||||||
Some parts of the system have dedicated maintainers with their own
|
Some parts of the system have dedicated maintainers with their own
|
||||||
|
|
Loading…
Reference in a new issue