From 7e50b3f5dff0975ebf73b48e23f2f27c1842da88 Mon Sep 17 00:00:00 2001 From: Linus Arver Date: Thu, 18 Apr 2024 21:51:58 +0000 Subject: [PATCH 1/8] MyFirstContribution: mention contrib/contacts/git-contacts Although we've had this script since 4d06402b1b (contrib: add git-contacts helper, 2013-07-21), we don't mention it in our introductory docs. Do so now. Helped-by: Junio C Hamano Signed-off-by: Linus Arver Signed-off-by: Junio C Hamano --- Documentation/MyFirstContribution.txt | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index f06563e981..e41654c00a 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -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. From 824503ce88963b9d7f111215fdce073a504e76e7 Mon Sep 17 00:00:00 2001 From: Linus Arver Date: Thu, 18 Apr 2024 21:51:59 +0000 Subject: [PATCH 2/8] SubmittingPatches: clarify 'git-contacts' location 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 is located, to help readers who may not be familiar with such "contrib" scripts (and how they are not accessible with the usual "git " syntax). Signed-off-by: Linus Arver Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index e734a3f0f1..d4173d4fe8 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -493,9 +493,13 @@ 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 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` 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 From 84b91fc465a869cfb30084dca1831e432461e18a Mon Sep 17 00:00:00 2001 From: Linus Arver Date: Thu, 18 Apr 2024 21:52:00 +0000 Subject: [PATCH 3/8] SubmittingPatches: mention GitGitGadget Signed-off-by: Linus Arver Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index d4173d4fe8..26055a1fe2 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -408,6 +408,10 @@ 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 From c8d6a54a073a179a1178fd17332dc51accbaff18 Mon Sep 17 00:00:00 2001 From: Linus Arver Date: Thu, 18 Apr 2024 21:52:01 +0000 Subject: [PATCH 4/8] SubmittingPatches: quote commands Signed-off-by: Linus Arver Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 26055a1fe2..6b9e954a47 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -403,7 +403,7 @@ Before sending any patches, please note that 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 +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. From e2663c459710fc6dbf11b614612844d3c15562a1 Mon Sep 17 00:00:00 2001 From: Linus Arver Date: Thu, 18 Apr 2024 21:52:02 +0000 Subject: [PATCH 5/8] SubmittingPatches: discuss reviewers first No matter how well someone configures their email tooling, understanding who to send the patches to is something that must always be considered. So discuss it first instead of at the end. In the following commit we will clean up the (now redundant) discussion about sending security patches to the Git Security mailing list. Signed-off-by: Linus Arver Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 66 +++++++++++++++++---------------- 1 file changed, 34 insertions(+), 32 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 6b9e954a47..5d5046fa95 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -397,6 +397,40 @@ letter. [[send-patches]] === Sending your patches. +==== Choosing your reviewers + +: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}. + +: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. + +: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. + :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 @@ -490,38 +524,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}. - -: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. - -: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 From 01ea2b2836d8caa8ff08f81d4d3dfb5c0264b629 Mon Sep 17 00:00:00 2001 From: Linus Arver Date: Thu, 18 Apr 2024 21:52:03 +0000 Subject: [PATCH 6/8] SubmittingPatches: dedupe discussion of security patches Signed-off-by: Linus Arver Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 5d5046fa95..dd248513a5 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -399,12 +399,11 @@ letter. ==== Choosing your reviewers -:security-ml-ref: footnoteref:[security-ml] +:security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com] -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}. +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. :contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are + not part of the core `git` binary and must be called directly. Clone the Git + @@ -431,12 +430,6 @@ 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. -: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 -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 are optimized for the workflow of sending patches, avoiding many ways your existing e-mail client (often optimized for "multipart/*" MIME From bf966145419f46b9370558c89428ac89e3fdc9dc Mon Sep 17 00:00:00 2001 From: Linus Arver Date: Thu, 18 Apr 2024 21:52:04 +0000 Subject: [PATCH 7/8] SubmittingPatches: add heading for format-patch and send-email Signed-off-by: Linus Arver Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index dd248513a5..ef3985459a 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -430,6 +430,8 @@ 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 From 61e124bb2d0ae475b627abf76f53709c300cf44d Mon Sep 17 00:00:00 2001 From: Linus Arver Date: Thu, 18 Apr 2024 21:52:05 +0000 Subject: [PATCH 8/8] SubmittingPatches: demonstrate using git-contacts with git-send-email Signed-off-by: Linus Arver Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index ef3985459a..b684e28c0d 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -417,6 +417,13 @@ 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]