From 2d194548cb8c16d17925be0f0e8ce946eb6d1f6e Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 28 Dec 2023 04:55:16 +0000 Subject: [PATCH 1/9] CodingGuidelines: move period inside parentheses The contents within parenthesis should be omittable without resulting in broken text. Eliding the parenthesis left a period to end a run without any content. Signed-off-by: Josh Soref Signed-off-by: Junio C Hamano --- Documentation/CodingGuidelines | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 8d3a467c01..b64e52fdbe 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -450,7 +450,7 @@ For C programs: one of the approved headers that includes it first for you. (The approved headers currently include "builtin.h", "t/helper/test-tool.h", "xdiff/xinclude.h", or - "reftable/system.h"). You do not have to include more than one of + "reftable/system.h".) You do not have to include more than one of these. - A C file must directly include the header files that declare the From e6397c5cc83979d4808e9aeeb0276d3302987782 Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 28 Dec 2023 04:55:17 +0000 Subject: [PATCH 2/9] CodingGuidelines: write punctuation marks - Match style in Release Notes Signed-off-by: Josh Soref Signed-off-by: Junio C Hamano --- Documentation/CodingGuidelines | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index b64e52fdbe..169d4eb3ac 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -578,7 +578,7 @@ Externally Visible Names . The variable name describes the effect of tweaking this knob. The section and variable names that consist of multiple words are - formed by concatenating the words without punctuations (e.g. `-`), + formed by concatenating the words without punctuation marks (e.g. `-`), and are broken using bumpyCaps in documentation as a hint to the reader. From 127106294a591ebbc8400ac691e271b58e843f09 Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 28 Dec 2023 04:55:18 +0000 Subject: [PATCH 3/9] SubmittingPatches: drop ref to "What's in git.git" "What's in git.git" was last seen in 2010: https://lore.kernel.org/git/?q=%22what%27s+in+git.git%22 https://lore.kernel.org/git/7vaavikg72.fsf@alter.siamese.dyndns.org/ Signed-off-by: Josh Soref 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 bce7f97815..32e9023877 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -570,7 +570,7 @@ their trees themselves. master). * Read the Git mailing list, the maintainer regularly posts messages - entitled "What's cooking in git.git" and "What's in git.git" giving + entitled "What's cooking in git.git" giving the status of various proposed changes. == GitHub CI[[GHCI]] From ac9fff2bf1ca4174efeac57ff1ef43df8a6b9517 Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 28 Dec 2023 04:55:19 +0000 Subject: [PATCH 4/9] SubmittingPatches: discourage new trailers There seems to be consensus amongst the core Git community on a working set of common trailers, and there are non-trivial costs to people inventing new trailers (research to discover what they mean/how they differ from existing trailers) such that inventing new ones is generally unwarranted and not something to be recommended to new contributors. Suggested-by: Elijah Newren Signed-off-by: Josh Soref Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 32e9023877..58dfe40504 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -356,8 +356,9 @@ If you like, you can put extra tags at the end: . `Tested-by:` is used to indicate that the person applied the patch and found it to have the desired effect. -You can also create your own tag or use one that's in common usage -such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". +While you can also create your own trailer if the situation warrants it, we +encourage you to instead use one of the common trailers in this project +highlighted above. [[git-tools]] === Generate your patch using Git tools out of your commits. From c771ef6f77d36fc9bfe6e70f805f52f84f681536 Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 28 Dec 2023 04:55:20 +0000 Subject: [PATCH 5/9] SubmittingPatches: update extra tags list Add items with at least 100 uses in the past three years: - Co-authored-by - Helped-by - Mentored-by - Suggested-by git log --since=3.years| perl -ne 'next unless /^\s+[A-Z][a-z]+-\S+:/;s/^\s+//;s/:.*/:/;print'| sort|uniq -c|sort -n|grep '[0-9][0-9] ' 14 Based-on-patch-by: 14 Original-patch-by: 17 Tested-by: 100 Suggested-by: 121 Co-authored-by: 163 Mentored-by: 274 Reported-by: 290 Acked-by: 450 Helped-by: 602 Reviewed-by: 14111 Signed-off-by: Signed-off-by: Josh Soref Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 58dfe40504..31878cb70b 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -355,6 +355,14 @@ If you like, you can put extra tags at the end: patch after a detailed analysis. . `Tested-by:` is used to indicate that the person applied the patch and found it to have the desired effect. +. `Co-authored-by:` is used to indicate that people exchanged drafts + of a patch before submitting it. +. `Helped-by:` is used to credit someone who suggested ideas for + changes without providing the precise changes in patch form. +. `Mentored-by:` is used to credit someone with helping develop a + patch as part of a mentorship program (e.g., GSoC or Outreachy). +. `Suggested-by:` is used to credit someone with suggesting the idea + for a patch. While you can also create your own trailer if the situation warrants it, we encourage you to instead use one of the common trailers in this project From 08e2e6f8d27539b7573c9ce3b5e4958b93876229 Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 28 Dec 2023 04:55:21 +0000 Subject: [PATCH 6/9] SubmittingPatches: provide tag naming advice Current statistics show a strong preference to only capitalize the first letter in a hyphenated tag, but that some guidance would be helpful: git log | perl -ne 'next unless /^\s+(?:Signed-[oO]ff|Acked)-[bB]y:/; s/^\s+//;s/:.*/:/;print'| sort|uniq -c|sort -n 2 Signed-off-By: 4 Signed-Off-by: 22 Acked-By: 47 Signed-Off-By: 2202 Acked-by: 95315 Signed-off-by: Signed-off-by: Josh Soref Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 31878cb70b..94c874ab5e 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -368,6 +368,9 @@ While you can also create your own trailer if the situation warrants it, we encourage you to instead use one of the common trailers in this project highlighted above. +Only capitalize the very first letter of tags, i.e. favor +"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By". + [[git-tools]] === Generate your patch using Git tools out of your commits. From 0771a3b55ca137f32567635c1a96222892bd7499 Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 28 Dec 2023 04:55:22 +0000 Subject: [PATCH 7/9] SubmittingPatches: clarify GitHub visual GitHub has two general forms for its states, sometimes they're a simple colored object (e.g. green check or red x), and sometimes there's also a colored container (e.g. green box or red circle) which contains that object (e.g. check or x). That's a lot of words to try to describe things, but in general, the key for a failure is that it's recognized as an `x` and that it's associated with the color red -- the color of course is problematic for people who are red-green color-blind, but that's why they are paired with distinct shapes. Signed-off-by: Josh Soref Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 94c874ab5e..0665f89f38 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -602,11 +602,11 @@ After the initial setup, CI will run whenever you push new changes to your fork of Git on GitHub. You can monitor the test state of all your branches here: `https://github.com//git/actions/workflows/main.yml` -If a branch did not pass all test cases then it is marked with a red -cross. In that case you can click on the failing job and navigate to -"ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You -can also download "Artifacts" which are tarred (or zipped) archives -with test data relevant for debugging. +If a branch does not pass all test cases then it will be marked with a +red +x+, instead of a green check. In that case, you can click on the +failing job and navigate to "ci/run-build-and-tests.sh" and/or +"ci/print-test-failures.sh". You can also download "Artifacts" which +are tarred (or zipped) archives with test data relevant for debugging. Then fix the problem and push your fix to your GitHub fork. This will trigger a new CI build to ensure all tests pass. From 7818951623a0c98b54ab3cc0563f0e7be8af79c0 Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 28 Dec 2023 04:55:23 +0000 Subject: [PATCH 8/9] SubmittingPatches: clarify GitHub artifact format GitHub wraps artifacts generated by workflows in a .zip file. Internally, workflows can package anything they like in them. A recently generated failure artifact had the form: windows-artifacts.zip Length Date Time Name --------- ---------- ----- ---- 76001695 12-19-2023 01:35 artifacts.tar.gz 11005650 12-19-2023 01:35 tracked.tar.gz --------- ------- 87007345 2 files Signed-off-by: Josh Soref Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 0665f89f38..5e2e13b5e0 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -606,7 +606,8 @@ If a branch does not pass all test cases then it will be marked with a red +x+, instead of a green check. In that case, you can click on the failing job and navigate to "ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You can also download "Artifacts" which -are tarred (or zipped) archives with test data relevant for debugging. +are zip archives containing tarred (or zipped) archives with test data +relevant for debugging. Then fix the problem and push your fix to your GitHub fork. This will trigger a new CI build to ensure all tests pass. From 291873e5d6247f2e965b3937b9bd75f3b87830fa Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 28 Dec 2023 04:55:24 +0000 Subject: [PATCH 9/9] SubmittingPatches: hyphenate non-ASCII Git documentation does this with the exception of ancient release notes. Signed-off-by: Josh Soref 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 5e2e13b5e0..e734a3f0f1 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -699,7 +699,7 @@ message to an external program, and this is a handy way to drive `git am`. However, if the message is MIME encoded, what is piped into the program is the representation you see in your `*Article*` buffer after unwrapping MIME. This is often not what -you would want for two reasons. It tends to screw up non ASCII +you would want for two reasons. It tends to screw up non-ASCII characters (most notably in people's names), and also whitespaces (fatal in patches). Running "C-u g" to display the message in raw form before using "|" to run the pipe can work