From 2d194548cb8c16d17925be0f0e8ce946eb6d1f6e Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 28 Dec 2023 04:55:16 +0000 Subject: 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 -- cgit v1.2.3 From e6397c5cc83979d4808e9aeeb0276d3302987782 Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 28 Dec 2023 04:55:17 +0000 Subject: 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. -- cgit v1.2.3 From 127106294a591ebbc8400ac691e271b58e843f09 Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 28 Dec 2023 04:55:18 +0000 Subject: 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]] -- cgit v1.2.3 From ac9fff2bf1ca4174efeac57ff1ef43df8a6b9517 Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 28 Dec 2023 04:55:19 +0000 Subject: 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. -- cgit v1.2.3 From c771ef6f77d36fc9bfe6e70f805f52f84f681536 Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 28 Dec 2023 04:55:20 +0000 Subject: 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 -- cgit v1.2.3 From 08e2e6f8d27539b7573c9ce3b5e4958b93876229 Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 28 Dec 2023 04:55:21 +0000 Subject: 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. -- cgit v1.2.3 From 0771a3b55ca137f32567635c1a96222892bd7499 Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 28 Dec 2023 04:55:22 +0000 Subject: 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. -- cgit v1.2.3 From 7818951623a0c98b54ab3cc0563f0e7be8af79c0 Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 28 Dec 2023 04:55:23 +0000 Subject: 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. -- cgit v1.2.3 From 291873e5d6247f2e965b3937b9bd75f3b87830fa Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 28 Dec 2023 04:55:24 +0000 Subject: 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 -- cgit v1.2.3