mirror/ git
1
0
Fork 0
mirror of https://github.com/git/git.git synced 2024-05-05 11:46:10 +02:00
Code

Merge branch 'la/doc-use-of-contacts-when-contributing' into next 

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:
Junio C Hamano 2024-04-25 10:37:10 -07:00
parent 59bd9d5e25 61e124bb2d
commit 5102a45f63
2 changed files with 51 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
Documentation/MyFirstContribution.txt
View File

@ -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
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
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.

72
Documentation/SubmittingPatches
View File

@ -397,17 +397,57 @@ letter.
[[send-patches]]
=== Sending your patches.
==== Choosing your reviewers
: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
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
your existing e-mail client (often optimized for "multipart/*" MIME
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
comment on the changes you are submitting. It is important for
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
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
Some parts of the system have dedicated maintainers with their own