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

Message

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

Make git-contacts more prominent in our docs.


Notable changes in v5
=====================

 * Drop mention of "/usr/share/..." as an "installed" path for
   "git-contacts"; instead point users to the script as a relative path
   inside the Git codebase
 * Minor wording tweaks to commit messages


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 | 10 ++++
 Documentation/SubmittingPatches       | 73 ++++++++++++++++-----------
 2 files changed, 53 insertions(+), 30 deletions(-)


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

Range-diff vs v4:

 1:  ad469e4e6db ! 1:  d2c9551ee0e MyFirstContribution: mention contrib/contacts/git-contacts
     @@ 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.
       
     -+: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, 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.]
     ++: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 `contrib/contacts/git-contacts` (you must have Perl installed +
     ++in your system).]
      +
      +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
     ++--cc-cmd='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 [e-mail] - but
 2:  c43de19d867 ! 2:  92d72a8a25a SubmittingPatches: clarify 'git-contacts' location
     @@ Metadata
       ## Commit message ##
          SubmittingPatches: clarify 'git-contacts' location
      
     -    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
     +    Use a dash ("git-contacts", not "git contacts") because the script is
     +    not installed as part of "git" toolset. 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
      
     -    . 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).
     +    Also add a footnote to describe where the script is 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: security relevant should not be submitted to th
       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.]
     ++: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 `contrib/contacts/git-contacts` (you must have Perl installed +
     ++in your system).]
      +
       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
 3:  cd941704176 = 3:  7c4cc5a91f0 SubmittingPatches: mention GitGitGadget
 4:  44470a5d70e = 4:  621912a64fb SubmittingPatches: quote commands
 5:  15f9356ff97 ! 5:  8f44343c482 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.]
     ++: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 `contrib/contacts/git-contacts` (you must have Perl installed +
     ++in your system).]
      +
      +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`
     @@ 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.]
     +-: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 `contrib/contacts/git-contacts` (you must have Perl installed +
     +-in your system).]
      -
      -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`
 6:  e889e64bd45 ! 6:  fd8ad38cab0 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.
       
     - :contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
     - part of the core `git` binary and must be called separately. Consult your +
     + :contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
     + not part of the core `git` binary and must be called directly. Clone the Git +
      @@ 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:  81556298599 = 7:  b23c73459cc SubmittingPatches: add heading for format-patch and send-email
 8:  84b1cf3f914 ! 8:  911d4f2a0e5 SubmittingPatches: demonstrate using git-contacts with git-send-email
     @@ Documentation/SubmittingPatches: trial merges of your topic to `next` and `seen`
       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
     ++If you are using `send-email`, you can feed it the output of `git-contacts` like
      +this:
      +
      +....
     -+	git send-email --cc-cmd='git contacts' feature/*.patch
     ++	git send-email --cc-cmd='contrib/contacts/git-contacts' feature/*.patch
      +....
      +
       :current-maintainer: footnote:[The current maintainer: [e-mail]]