[v4,0/8] docs: recommend using contrib/contacts/git-contacts

Message

Philippe Blain via GitGitGadget April 11, 2024, 11:32 p.m. UTC

Make git-contacts more prominent in our docs.


Notable changes in v4
=====================

 * Avoid using "should" for guidance around using "git-contacts"
 * Clarify where to find the "git-contacts" script (because it's not a
   default builtin command)


Notable changes in v3
=====================

 * Refer to GitGitGadget via a link to MyFirstContribution (instead of
   sending readers to GGG's homepage directly)
 * Soften the advice for using git-contacts


Notable changes in v2
=====================

 * Improve existing mention of git-contacts in SubmittingPatches (instead of
   adding a separate, entirely new paragraph)
 * Add example usage of integrating git-contacts with git-send-email with
   the latter's --cc-cmd flag.
 * Various smaller fixes to SubmittingPatches

Linus Arver (8):
  MyFirstContribution: mention contrib/contacts/git-contacts
  SubmittingPatches: clarify 'git-contacts' location
  SubmittingPatches: mention GitGitGadget
  SubmittingPatches: quote commands
  SubmittingPatches: discuss reviewers first
  SubmittingPatches: dedupe discussion of security patches
  SubmittingPatches: add heading for format-patch and send-email
  SubmittingPatches: demonstrate using git-contacts with git-send-email

 Documentation/MyFirstContribution.txt | 12 +++++
 Documentation/SubmittingPatches       | 75 ++++++++++++++++-----------
 2 files changed, 57 insertions(+), 30 deletions(-)


base-commit: c2cbfbd2e28cbe27c194d62183b42f27a6a5bb87
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1704%2Flistx%2Freviewers-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1704/listx/reviewers-v4
Pull-Request: https://github.com/gitgitgadget/git/pull/1704

Range-diff vs v3:

 1:  1f65dc5ba3d ! 1:  ad469e4e6db MyFirstContribution: mention contrib/contacts/git-contacts
     @@ Commit message
          git-contacts helper, 2013-07-21), we don't mention it in our
          introductory docs. Do so now.
      
     +    Helped-by: Junio C Hamano <[e-mail]>
          Signed-off-by: Linus Arver <[e-mail]>
      
       ## Documentation/MyFirstContribution.txt ##
     @@ Documentation/MyFirstContribution.txt: $ git send-email --to=[e-mail]
       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.
       
     -+NOTE: If you're not sure who to CC, use `contrib/contacts/git-contacts` to get a
     -+list of reviewers you should include in the CC list. In addition, you can do
     -+`git send-email --cc-cmd='git contacts' feature/*.patch` to automatically pass
     -+this list of emails to `send-email`.
     ++:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
     ++part of the core `git` binary and must be called separately. Consult your +
     ++package manager to determine where it is located. For example&#44; on Ubuntu-based +
     ++systems it could be installed under +
     ++`/usr/share/doc/git/contrib/contacts/git-contacts` and may need to be called +
     ++with `perl ...` if it does not have the executable bit set.]
     ++
     ++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='/path/to/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 [e-mail] - but
       please don't send your patchset from the tutorial to the real mailing list! For
 2:  6e8b1b50ac5 ! 2:  c43de19d867 SubmittingPatches: make 'git contacts' grep-friendly
     @@ Metadata
      Author: Linus Arver <[e-mail]>
      
       ## Commit message ##
     -    SubmittingPatches: make 'git contacts' grep-friendly
     +    SubmittingPatches: clarify 'git-contacts' location
      
     -    Avoid splitting up the command over two lines. This way, a command like
     +    Use a dash ("git-contacts", not "git contacts") because the script
     +    is not a core builtin command that is compiled into the `git` binary.
     +    This also puts the script on one line, which should make it easier to
     +    grep for with a loose search query, such as
      
              $ git grep git.contacts Documentation
      
     -    will return a positive hit for this location.
     +    . Also add a footnote to describe where the script could actually be
     +    located, to help readers who may not be familiar with such "contrib"
     +    scripts (and how they are not accessible with the usual "git
     +    <subcommand>" syntax).
      
          Signed-off-by: Linus Arver <[e-mail]>
      
       ## Documentation/SubmittingPatches ##
     -@@ Documentation/SubmittingPatches: mentioned below, but should instead be sent privately to the Git
     +@@ Documentation/SubmittingPatches: 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}.
       
     ++:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
     ++part of the core `git` binary and must be called separately. Consult your +
     ++package manager to determine where it is located. For example&#44; on Ubuntu-based +
     ++systems it could be installed under +
     ++`/usr/share/doc/git/contrib/contacts/git-contacts` and may need to be called +
     ++with `perl ...` if it does not have the executable bit set.]
     ++
       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
     -+people who are involved in the area you are touching (the `git contacts`
     -+command in `contrib/contacts/` can help to
     ++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
 3:  7f8fdc053f7 = 3:  cd941704176 SubmittingPatches: mention GitGitGadget
 4:  ef26bdb75c5 = 4:  44470a5d70e SubmittingPatches: quote commands
 5:  6f71b1731f2 ! 5:  15f9356ff97 SubmittingPatches: discuss reviewers first
     @@ Documentation/SubmittingPatches: letter.
      +mentioned below, but should instead be sent privately to the Git
      +Security mailing list{security-ml-ref}.
      +
     ++:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
     ++part of the core `git` binary and must be called separately. Consult your +
     ++package manager to determine where it is located. For example&#44; on Ubuntu-based +
     ++systems it could be installed under +
     ++`/usr/share/doc/git/contrib/contacts/git-contacts` and may need to be called +
     ++with `perl ...` if it does not have the executable bit set.]
     ++
      +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
     ++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
     @@ Documentation/SubmittingPatches: patch, format it as "multipart/signed", not a t
      -mentioned below, but should instead be sent privately to the Git
      -Security mailing list{security-ml-ref}.
      -
     +-:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
     +-part of the core `git` binary and must be called separately. Consult your +
     +-package manager to determine where it is located. For example&#44; on Ubuntu-based +
     +-systems it could be installed under +
     +-`/usr/share/doc/git/contrib/contacts/git-contacts` and may need to be called +
     +-with `perl ...` if it does not have the executable bit set.]
     +-
      -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
     +-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
 6:  f5e44f69941 ! 6:  e889e64bd45 SubmittingPatches: dedupe discussion of security patches
     @@ Documentation/SubmittingPatches: letter.
      +security relevant should be submitted privately to the Git Security
      +mailing list{security-ml}, instead of the public mailing 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 `git contacts`
     + :contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
     + part of the core `git` binary and must be called separately. Consult your +
      @@ Documentation/SubmittingPatches: 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.
 7:  e64fc5c888a = 7:  81556298599 SubmittingPatches: add heading for format-patch and send-email
 8:  4fcab0d3319 = 8:  84b1cf3f914 SubmittingPatches: demonstrate using git-contacts with git-send-email