# [PATCH 0/8] Minor improvements to CodingGuidelines and SubmittingPatches 55 messages from 2023-12-19 to 2023-12-28. Participants: Josh Soref via GitGitGadget, René Scharfe, Phillip Wood, Elijah Newren, Josh Soref, Junio C Hamano, phillip.wood123@gmail.com, Dragan Simic. Thread: https://gitlist.dev/t/60631 ## Josh Soref via GitGitGadget, 2023-12-19 08:41 Subject: [PATCH 0/8] Minor improvements to CodingGuidelines and SubmittingPatches Message-ID: URL: https://gitlist.dev/e/pull.1623.git.1702975319.gitgitgadget%40gmail.com ``` These are a bunch of things I've run into over my past couple of attempts to contribute to Git. * Incremental punctuation/grammatical improvements * Update extra tags suggestions based on common usage * drop reference to an article that was discontinued over a decade ago * update GitHub references * harmonize non-ASCII while I'm here Note that I'm trying to do things "in the neighborhood". It'll be slower than me replacing things topically, but hopefully easier for others to digest. My current estimate is a decade or two :). Josh Soref (8): CodingGuidelines: move period inside parentheses CodingGuidelines: write punctuation marks SubmittingPatches: drop ref to "What's in git.git" SubmittingPatches: update extra tags list SubmittingPatches: improve extra tags advice SubmittingPatches: clarify GitHub visual SubmittingPatches: clarify GitHub artifact format SubmittingPatches: hyphenate non-ASCII Documentation/CodingGuidelines | 4 ++-- Documentation/SubmittingPatches | 24 +++++++++++++++++++----- 2 files changed, 21 insertions(+), 7 deletions(-) base-commit: 624eb90fa8f65a79396615f3c2842ac5a3743350 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1623%2Fjsoref%2Fdocumentation-v1 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1623/jsoref/documentation-v1 Pull-Request: https://github.com/gitgitgadget/git/pull/1623 -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-19 08:41 Subject: [PATCH 1/8] CodingGuidelines: move period inside parentheses Message-ID: URL: https://gitlist.dev/e/b9a8eb6aa4e87cd96fbf2b5d514350508076d756.1702975319.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref 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 --- Documentation/CodingGuidelines | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 8ed517a5ca0..af94ed3a75d 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 -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-19 08:41 Subject: [PATCH 2/8] CodingGuidelines: write punctuation marks Message-ID: URL: https://gitlist.dev/e/c0db8336e519cb43767effbe842dc8b97f914a4b.1702975319.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref - Match style in Release Notes Signed-off-by: Josh Soref --- Documentation/CodingGuidelines | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index af94ed3a75d..578587a4715 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. -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-19 08:41 Subject: [PATCH 3/8] SubmittingPatches: drop ref to "What's in git.git" Message-ID: <22d66c5b78a6930e195141df848266cac099ca08.1702975320.git.gitgitgadget@gmail.com> URL: https://gitlist.dev/e/22d66c5b78a6930e195141df848266cac099ca08.1702975320.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref "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 --- Documentation/SubmittingPatches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index bce7f97815c..32e90238777 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]] -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-19 08:41 Subject: [PATCH 4/8] SubmittingPatches: update extra tags list Message-ID: URL: https://gitlist.dev/e/e5c7f29af439c48f59b2f35af93a7972e66a5b6b.1702975320.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref Add items with at least 100 uses: - Co-authored-by - Helped-by - Mentored-by - Suggested-by Updating the create suggestion to something less commonly used. git log | perl -ne 'next unless /^\s+[A-Z][a-z]+-\S+:/;s/^\s+//;s/:.*/:/;print'| sort|uniq -c|sort -n|grep '[0-9][0-9] ' 11 Helped-By: 13 Message-ID: 14 Reported-By: 22 Acked-By: 27 Inspired-by: 29 Requested-by: 35 Original-patch-by: 43 Contributions-by: 47 Signed-Off-By: 65 Based-on-patch-by: 68 Thanks-to: 88 Improved-by: 145 Co-authored-by: 171 Noticed-by: 182 Tested-by: 361 Suggested-by: 469 Mentored-by: 1196 Reported-by: 1727 Helped-by: 2177 Reviewed-by: 2202 Acked-by: 95313 Signed-off-by: Signed-off-by: Josh Soref --- Documentation/SubmittingPatches | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 32e90238777..694a7bafb68 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -348,6 +348,8 @@ If you like, you can put extra tags at the end: . `Reported-by:` is used to credit someone who found the bug that the patch attempts to fix. +. `Noticed-by:` liked `Reported-by:` indicates someone who noticed + the item being fixed. . `Acked-by:` says that the person who is more familiar with the area the patch attempts to modify liked the patch. . `Reviewed-by:`, unlike the other tags, can only be offered by the @@ -355,9 +357,17 @@ 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 multiple people + contributed to the work of a patch. +. `Helped-by:` is used to credit someone with helping develop a + patch. +. `Mentored-by:` is used to credit someone with helping develop a + patch. +. `Suggested-by:` is used to credit someone with suggesting the idea + for a patch. 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:". +such as "Thanks-to:", "Based-on-patch-by:", or "Improved-by:". [[git-tools]] === Generate your patch using Git tools out of your commits. -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-19 08:41 Subject: [PATCH 5/8] SubmittingPatches: improve extra tags advice Message-ID: <11688e4360c1698e56b3485e3df4e171397d3c3c.1702975320.git.gitgitgadget@gmail.com> URL: https://gitlist.dev/e/11688e4360c1698e56b3485e3df4e171397d3c3c.1702975320.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref 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 --- Documentation/SubmittingPatches | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 694a7bafb68..d7a84f59478 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -369,6 +369,9 @@ If you like, you can put extra tags at the end: You can also create your own tag or use one that's in common usage such as "Thanks-to:", "Based-on-patch-by:", or "Improved-by:". +Extra tags should only capitalize the very first letter, 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. -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-19 08:41 Subject: [PATCH 6/8] SubmittingPatches: clarify GitHub visual Message-ID: <043d2a24202d39c5564e4a4369c86ae4648dd721.1702975320.git.gitgitgadget@gmail.com> URL: https://gitlist.dev/e/043d2a24202d39c5564e4a4369c86ae4648dd721.1702975320.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref Some people would expect a cross to be upright, and potentially have unequal lengths... GitHub uses a white x overlaying a solid red circle to indicate failure. Signed-off-by: Josh Soref --- Documentation/SubmittingPatches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index d7a84f59478..8e19c7f82e4 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -604,7 +604,7 @@ 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 ++x+. 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. -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-19 08:41 Subject: [PATCH 7/8] SubmittingPatches: clarify GitHub artifact format Message-ID: URL: https://gitlist.dev/e/cdab65a425944e9d10f6aa6be378162cd5450c81.1702975320.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref 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 --- Documentation/SubmittingPatches | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 8e19c7f82e4..b4fa52ae348 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -606,7 +606,8 @@ branches here: `https://github.com//git/actions/workflows/ma If a branch did not pass all test cases then it is marked with a red +x+. 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 +can also download "Artifacts" which 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 -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-19 08:41 Subject: [PATCH 8/8] SubmittingPatches: hyphenate non-ASCII Message-ID: <92469324813702418a9db0b2e760580518b225cd.1702975320.git.gitgitgadget@gmail.com> URL: https://gitlist.dev/e/92469324813702418a9db0b2e760580518b225cd.1702975320.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref Git documentation does this with the exception of ancient release notes. Signed-off-by: Josh Soref --- Documentation/SubmittingPatches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index b4fa52ae348..3c53592cfc8 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -700,7 +700,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 -- gitgitgadget ``` ## René Scharfe, 2023-12-19 14:44 Subject: Re: [PATCH 6/8] SubmittingPatches: clarify GitHub visual Message-ID: URL: https://gitlist.dev/e/e788cf7b-56c7-48c2-ad4f-65d9c9e73ad5%40web.de In-Reply-To: <043d2a24202d39c5564e4a4369c86ae4648dd721.1702975320.git.gitgitgadget@gmail.com> ``` Am 19.12.23 um 09:41 schrieb Josh Soref via GitGitGadget: > From: Josh Soref > > Some people would expect a cross to be upright, and potentially have > unequal lengths... There are lots of types of crosses. And while looking them up on Wikipedia I learned today that an x-cross is called "saltire" in English. I only knew it as St. Andrew's cross before. > GitHub uses a white x overlaying a solid red circle to indicate failure. They call it "x-circle-fill" (https://primer.github.io/octicons/x-circle-fill-16). > > Signed-off-by: Josh Soref > --- > Documentation/SubmittingPatches | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > index d7a84f59478..8e19c7f82e4 100644 > --- a/Documentation/SubmittingPatches > +++ b/Documentation/SubmittingPatches > @@ -604,7 +604,7 @@ 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 > ++x+. In that case you can click on the failing job and navigate to In the commit message you say the x is white, here it's red, so what is it? IIUC the circle is red and the x-cross inside is the same color as the background, i.e. white in light mode and black in dark mode. No idea how to express that in one word. Perhaps "red circle containing and x-cross"? René ``` ## Phillip Wood, 2023-12-20 15:18 Subject: Re: [PATCH 4/8] SubmittingPatches: update extra tags list Message-ID: <35fc350d-018a-49cf-a28e-e5ce21fe7dec@gmail.com> URL: https://gitlist.dev/e/35fc350d-018a-49cf-a28e-e5ce21fe7dec%40gmail.com In-Reply-To: ``` Hi Josh On 19/12/2023 08:41, Josh Soref via GitGitGadget wrote: > From: Josh Soref > > Add items with at least 100 uses: > - Co-authored-by > - Helped-by > - Mentored-by > - Suggested-by Thanks for adding these, they are widely used and should be documented. The patch also adds a mention for "Noticed-by:" - I'm less convinced by the need for that as I explain below. > Updating the create suggestion to something less commonly used. I'm not quite sure I understand what you mean by this sentence. > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > index 32e90238777..694a7bafb68 100644 > --- a/Documentation/SubmittingPatches > +++ b/Documentation/SubmittingPatches > @@ -348,6 +348,8 @@ If you like, you can put extra tags at the end: > > . `Reported-by:` is used to credit someone who found the bug that > the patch attempts to fix. > +. `Noticed-by:` liked `Reported-by:` indicates someone who noticed > + the item being fixed. I wonder if we really need a separate "Noticed-by" footer in addition to "Reported-by". Personally I use the latter to acknowledge the person who reported the issue being fix regards of weather I'm fixing a bug or some other issue. > . `Acked-by:` says that the person who is more familiar with the area > the patch attempts to modify liked the patch. > . `Reviewed-by:`, unlike the other tags, can only be offered by the > @@ -355,9 +357,17 @@ 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 multiple people > + contributed to the work of a patch. Junio's comments in [1] may be helpful here If co-authors closely worked together (possibly but not necessarily outside the public view), exchanging drafts and agreeing on the final version before sending it to the list, by one approving the other's final draft, Co-authored-by may be appropriate. I would prefer to see more use of Helped-by when suggestions for improvements were made, possibly but not necessarily in a concrete "squashable patch" form, the original author accepted before sending the new version out, and the party who made suggestions saw the updated version at the same time as the general public. So I think we should be clear that "Co-authored-by:" means that multiple authors worked closely together on the patch, rather than just contributed to it. [1] https://lore.kernel.org/git/xmqqmth8wwcf.fsf@gitster.g/ > +. `Helped-by:` is used to credit someone with helping develop a > + patch. > +. `Mentored-by:` is used to credit someone with helping develop a > + patch. I think we use "Montored-by:" specifically to credit the mentor on patches written by GSoC or Outreachy interns and "Helped-by:" for the general case of someone helping the patch author. > +. `Suggested-by:` is used to credit someone with suggesting the idea > + for a patch. > > 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:". > +such as "Thanks-to:", "Based-on-patch-by:", or "Improved-by:". What's the difference between "Improved-by:" and "Helped-by:"? In general I'd prefer for us not to encourage new trailers where we already have a suitable one in use. Thanks for working on this, it will be good to have better descriptions of our common trailers. Best Wishes Phillip ``` ## Elijah Newren, 2023-12-20 15:21 Subject: Re: [PATCH 7/8] SubmittingPatches: clarify GitHub artifact format Message-ID: URL: https://gitlist.dev/e/CABPp-BFbLN7dsKvm%2B___y6s8OWARhXB5BHq5N3sKWaf66RPzDg%40mail.gmail.com In-Reply-To: ``` On Tue, Dec 19, 2023 at 12:42 AM Josh Soref via GitGitGadget wrote: > > From: Josh Soref > > GitHub wraps artifacts generated by workflows in a .zip file. > > Internally workflows can package anything they like in them. s/Internally/Internal/? > > 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 > --- > Documentation/SubmittingPatches | 3 ++- > 1 file changed, 2 insertions(+), 1 deletion(-) > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > index 8e19c7f82e4..b4fa52ae348 100644 > --- a/Documentation/SubmittingPatches > +++ b/Documentation/SubmittingPatches > @@ -606,7 +606,8 @@ branches here: `https://github.com//git/actions/workflows/ma > If a branch did not pass all test cases then it is marked with a red > +x+. 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 > +can also download "Artifacts" which 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 > -- > gitgitgadget > ``` ## Elijah Newren, 2023-12-20 15:30 Subject: Re: [PATCH 4/8] SubmittingPatches: update extra tags list Message-ID: URL: https://gitlist.dev/e/CABPp-BH_iP2KjPi-5kW8ROQWfy8XoUmbGhyT-Y1dZGtCtZXQGQ%40mail.gmail.com In-Reply-To: <35fc350d-018a-49cf-a28e-e5ce21fe7dec@gmail.com> ``` To add to what Phillip said... On Wed, Dec 20, 2023 at 7:18 AM Phillip Wood wrote: > > Hi Josh > > On 19/12/2023 08:41, Josh Soref via GitGitGadget wrote: > > From: Josh Soref > > > > Add items with at least 100 uses: > > - Co-authored-by > > - Helped-by > > - Mentored-by > > - Suggested-by > > Thanks for adding these, they are widely used and should be documented. > The patch also adds a mention for "Noticed-by:" - I'm less convinced by > the need for that as I explain below. > > > Updating the create suggestion to something less commonly used. > > I'm not quite sure I understand what you mean by this sentence. Same. > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > > index 32e90238777..694a7bafb68 100644 > > --- a/Documentation/SubmittingPatches > > +++ b/Documentation/SubmittingPatches > > @@ -348,6 +348,8 @@ If you like, you can put extra tags at the end: > > > > . `Reported-by:` is used to credit someone who found the bug that > > the patch attempts to fix. > > +. `Noticed-by:` liked `Reported-by:` indicates someone who noticed > > + the item being fixed. > > I wonder if we really need a separate "Noticed-by" footer in addition to > "Reported-by". Personally I use the latter to acknowledge the person who > reported the issue being fix regards of weather I'm fixing a bug or some > other issue. I'm not sure I'd mention both either; feels like we're making it hard for users to choose. Also, I think there's a minor distinction between them, but it's hard to convey simply: To me, Reported-by suggests someone sent a mail to the list specifically about the bug or issue in question. Also, to me, Noticed-by suggests that during a back-and-forth discussion of some sort on another topic, a fellow Git contributor noticed an issue and mentioned it as an aside. But, that's how _I_ would have used them, I didn't do any digging to find out if that's really how they are used. Either way, if we're going to define them as synonyms, I'd rather we just left the less common one out. If there's a distinction, and it's not a pain to describe, then maybe it'd be worth adding both. If we do add both, though, we at least need to fix "liked" to "like" in your description. > > . `Acked-by:` says that the person who is more familiar with the area > > the patch attempts to modify liked the patch. > > . `Reviewed-by:`, unlike the other tags, can only be offered by the > > @@ -355,9 +357,17 @@ 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 multiple people > > + contributed to the work of a patch. > > Junio's comments in [1] may be helpful here > > If co-authors closely worked together (possibly but not necessarily > outside the public view), exchanging drafts and agreeing on the > final version before sending it to the list, by one approving the > other's final draft, Co-authored-by may be appropriate. > > I would prefer to see more use of Helped-by when suggestions for > improvements were made, possibly but not necessarily in a concrete > "squashable patch" form, the original author accepted before > sending the new version out, and the party who made suggestions saw > the updated version at the same time as the general public. > > So I think we should be clear that "Co-authored-by:" means that multiple > authors worked closely together on the patch, rather than just > contributed to it. > > [1] https://lore.kernel.org/git/xmqqmth8wwcf.fsf@gitster.g/ > > > +. `Helped-by:` is used to credit someone with helping develop a > > + patch. > > +. `Mentored-by:` is used to credit someone with helping develop a > > + patch. > > I think we use "Montored-by:" specifically to credit the mentor on > patches written by GSoC or Outreachy interns and "Helped-by:" for the > general case of someone helping the patch author. Yes; I'd like for these to be distinguished in this way or something similar. > > +. `Suggested-by:` is used to credit someone with suggesting the idea > > + for a patch. > > > > 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:". > > +such as "Thanks-to:", "Based-on-patch-by:", or "Improved-by:". > > What's the difference between "Improved-by:" and "Helped-by:"? In > general I'd prefer for us not to encourage new trailers where we already > have a suitable one in use. Agreed. > Thanks for working on this, it will be good to have better descriptions > of our common trailers. Agreed here as well; thanks for the work, Josh. ``` ## Elijah Newren, 2023-12-20 15:40 Subject: Re: [PATCH 6/8] SubmittingPatches: clarify GitHub visual Message-ID: URL: https://gitlist.dev/e/CABPp-BFU%2B4Xy8tVrU5qV3GX7Mr3-nOEtSgix3MSne5VVW2hz2Q%40mail.gmail.com In-Reply-To: ``` On Tue, Dec 19, 2023 at 6:44 AM René Scharfe wrote: > > Am 19.12.23 um 09:41 schrieb Josh Soref via GitGitGadget: > > From: Josh Soref > > > > Some people would expect a cross to be upright, and potentially have > > unequal lengths... > > There are lots of types of crosses. And while looking them up on > Wikipedia I learned today that an x-cross is called "saltire" in > English. I only knew it as St. Andrew's cross before. > > > GitHub uses a white x overlaying a solid red circle to indicate failure. > > They call it "x-circle-fill" > (https://primer.github.io/octicons/x-circle-fill-16). > > > > > Signed-off-by: Josh Soref > > --- > > Documentation/SubmittingPatches | 2 +- > > 1 file changed, 1 insertion(+), 1 deletion(-) > > > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > > index d7a84f59478..8e19c7f82e4 100644 > > --- a/Documentation/SubmittingPatches > > +++ b/Documentation/SubmittingPatches > > @@ -604,7 +604,7 @@ 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 > > ++x+. In that case you can click on the failing job and navigate to > > In the commit message you say the x is white, here it's red, so what is > it? IIUC the circle is red and the x-cross inside is the same color as > the background, i.e. white in light mode and black in dark mode. No > idea how to express that in one word. Perhaps "red circle containing > and x-cross"? There's an "and" vs "an" typo there, I think. I'm tempted to just oversimplify ("...marked with red."), but am slightly concerned about red/green color-blind folks. I suspect they'd figure it out anyway by comparing the checkmarks (within green) to the x's (within red), but if we want to be more detailed, perhaps we drop the "cross" altogether and just describe it literally: "...marked with a red circle containing a white x."? ``` ## Elijah Newren, 2023-12-20 15:43 Subject: Re: [PATCH 0/8] Minor improvements to CodingGuidelines and SubmittingPatches Message-ID: URL: https://gitlist.dev/e/CABPp-BF8s-qiXWPMSae0pB%2BeRLDRO47Fj-7YRfS38SQ%2B6bBMzA%40mail.gmail.com In-Reply-To: ``` On Tue, Dec 19, 2023 at 12:42 AM Josh Soref via GitGitGadget wrote: > > These are a bunch of things I've run into over my past couple of attempts to > contribute to Git. > > * Incremental punctuation/grammatical improvements > * Update extra tags suggestions based on common usage > * drop reference to an article that was discontinued over a decade ago > * update GitHub references > * harmonize non-ASCII while I'm here I commented on patches 4, 6, and 7 suggesting some changes. Patch 1 is "meh" to me, but it doesn't hurt anything. The other four all look like good cleanups to me. ``` ## Josh Soref, 2023-12-20 16:09 Subject: Re: [PATCH 4/8] SubmittingPatches: update extra tags list Message-ID: URL: https://gitlist.dev/e/CACZqfqAiSpGP5ABN7MZ50Za%3D-vAEKnqE0ravzEMbLJCByfRd8w%40mail.gmail.com In-Reply-To: ``` On Wed, Dec 20, 2023 at 10:30 AM Elijah Newren wrote: > On Wed, Dec 20, 2023 at 7:18 AM Phillip Wood wrote: > > Thanks for adding these, they are widely used and should be documented. > > The patch also adds a mention for "Noticed-by:" - I'm less convinced by > > the need for that as I explain below. > > > > > Updating the create suggestion to something less commonly used. > > > > I'm not quite sure I understand what you mean by this sentence. Tentatively rewritten as: Updating the "create your own tag" suggestion as 'Mentored-by' has been promoted. This commit is adding bulleted items including promoting 'Mentored-by', which means that the suggestion of "invent your own" would really need a new suggestion. Personally I'm not a fan of "invent your own", but I'm trying to follow "when in Rome" (which is a big thing in the Git process documentation covered by the two files subject to this series). More on this later. > > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > > > index 32e90238777..694a7bafb68 100644 > > > @@ -348,6 +348,8 @@ If you like, you can put extra tags at the end: > > > > > > . `Reported-by:` is used to credit someone who found the bug that > > > the patch attempts to fix. > > > +. `Noticed-by:` liked `Reported-by:` indicates someone who noticed > > > + the item being fixed. > > > > I wonder if we really need a separate "Noticed-by" footer in addition to > > "Reported-by". Personally I use the latter to acknowledge the person who > > reported the issue being fix regards of weather I'm fixing a bug or some > > other issue. > > I'm not sure I'd mention both either; feels like we're making it hard > for users to choose. Also, I think there's a minor distinction > between them, but it's hard to convey simply: To me, Reported-by > suggests someone sent a mail to the list specifically about the bug or > issue in question. Also, to me, Noticed-by suggests that during a > back-and-forth discussion of some sort on another topic, a fellow Git > contributor noticed an issue and mentioned it as an aside. But, > that's how _I_ would have used them, I didn't do any digging to find > out if that's really how they are used. Given that Noticed-by is more common than Co-authored-by, I have a hard time arguing that it shouldn't be included. You could see that I struggled with it based on my lousy first drafts [1]. Anyway, tentatively: . `Noticed-by:` like `Reported-by:` indicates a Git contributor who called the item (being fixed) out as an aside. Here, I'm struggling with the tension between "noticed-by probably hints that something is being fixed" and "noticed-by is addressing who suggested it and why we're attributing it to them" "as an aside" is itself an ellipsis for something like "as an aside to some unrelated discussion and didn't really circle back to it as a top level discussion point, but here we're closing the loop" -- but this is obviously way too long-winded to be the written form. > Either way, if we're going to define them as synonyms, I'd rather we > just left the less common one out. If there's a distinction, and it's > not a pain to describe, then maybe it'd be worth adding both. > > If we do add both, though, we at least need to fix "liked" to "like" > in your description. Right, it's a "first draft" [1]... > > > +. `Co-authored-by:` is used to indicate that multiple people > > > + contributed to the work of a patch. > > > > Junio's comments in [1] may be helpful here > > > > If co-authors closely worked together (possibly but not necessarily > > outside the public view), exchanging drafts and agreeing on the > > final version before sending it to the list, by one approving the > > other's final draft, Co-authored-by may be appropriate. > > > > I would prefer to see more use of Helped-by when suggestions for > > improvements were made, possibly but not necessarily in a concrete > > "squashable patch" form, the original author accepted before > > sending the new version out, and the party who made suggestions saw > > the updated version at the same time as the general public. > > > > So I think we should be clear that "Co-authored-by:" means that multiple > > authors worked closely together on the patch, rather than just > > contributed to it. Tentatively: . `Co-authored-by:` is used to indicate that people exchanged drafts of a patch before submitting it. Note that I'm dropping `multiple` -- people implies that. . `Helped-by:` is used to credit someone who suggested ideas for changes without providing the precise changes in patch form. > > I think we use "Montored-by:" specifically to credit the mentor on > > patches written by GSoC or Outreachy interns and "Helped-by:" for the > > general case of someone helping the patch author. > > Yes; I'd like for these to be distinguished in this way or something similar. . `Mentored-by:` is used to credit someone with helping develop a patch as part of a mentorship program (e.g., GSoC or Outreachy). > > > 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:". > > > +such as "Thanks-to:", "Based-on-patch-by:", or "Improved-by:". > > > > What's the difference between "Improved-by:" and "Helped-by:"? I dunno. This entire section (as I called out at the beginning) is frustrating... Anyway, see all of us struggle with it below: > > In > > general I'd prefer for us not to encourage new trailers where we already > > have a suitable one in use. If this text needs to survive without being drastically changed, it needs a warning saying "don't create a new tag if there's an already used tag that seems like it'll cover what you're trying to say -- here's how to review them...". Note that I'd argue the cost being asked of someone to do this research far exceeds what is reasonable to ask of a new contributor, which is why I'd rather say that new contributors shouldn't be inventing tags. > Agreed. I personally agree. I think encouraging non-core contributors to invent their own is not a good idea. It leads to various things (including inconsistently cased items because users fail to review the current set / understand them/their-construction). Saying that it's ok for core contributors to suggest a new tag and that if a core contributor suggests a new tag that the person writing the current series should just accept the tag and trust that it'll be ok. Note: I'm not going to draft wording to this effect on my own, and if I were to provide such a change, it'd be its own commit prior to the one here, because it's a significant process change as opposed to clarifying the list of recommended tags. > > Thanks for working on this, it will be good to have better descriptions > > of our common trailers. > > Agreed here as well; thanks for the work, Josh. [1] The Late Show With Stephen Colbert has a running segment called First Drafts which showcases lousy first drafts of greeting cards, they've https://www.cbsstore.com/products/the-late-show-with-stephen-colbert-first-drafts-greeting-card-pack-sc1193 ``` ## Josh Soref, 2023-12-20 16:16 Subject: Re: [PATCH 7/8] SubmittingPatches: clarify GitHub artifact format Message-ID: URL: https://gitlist.dev/e/CACZqfqDVBHyBCgUwAJDv838cvF4xTo_UobA-_s6hqTzTG1c9qg%40mail.gmail.com In-Reply-To: ``` Elijah Newren wrote: > > From: Josh Soref > > > > GitHub wraps artifacts generated by workflows in a .zip file. > > > > Internally workflows can package anything they like in them. > > s/Internally/Internal/? No, it's actually: s/Internally/Internally,/ In that, what a workflow does to structure the contents of a .zip artifact is an implementation decision of the workflow. ``` ## Josh Soref, 2023-12-20 16:25 Subject: Re: [PATCH 6/8] SubmittingPatches: clarify GitHub visual Message-ID: URL: https://gitlist.dev/e/CACZqfqCM88M%2BsaToOYVC7iXqFZdrivuq%3DKGLmh-Scx3H0ZSWrw%40mail.gmail.com In-Reply-To: ``` Elijah Newren wrote: > On Tue, Dec 19, 2023 at 6:44 AM René Scharfe wrote: > > Am 19.12.23 um 09:41 schrieb Josh Soref via GitGitGadget: > > > From: Josh Soref > > > Some people would expect a cross to be upright, and potentially have > > > unequal lengths... > > There are lots of types of crosses. And while looking them up on > > Wikipedia I learned today that an x-cross is called "saltire" in > > English. I only knew it as St. Andrew's cross before. > > > > > GitHub uses a white x overlaying a solid red circle to indicate failure. > > > > They call it "x-circle-fill" > > (https://primer.github.io/octicons/x-circle-fill-16). > > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > > > @@ -604,7 +604,7 @@ 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 > > > ++x+. In that case you can click on the failing job and navigate to > > > > In the commit message you say the x is white, here it's red, so what is > > it? IIUC the circle is red and the x-cross inside is the same color as > > the background, i.e. white in light mode and black in dark mode. No > > idea how to express that in one word. Perhaps "red circle containing > > and x-cross"? This was an oversimplification, which I deeply regret. It uses a simple red x (❌) in some views, e.g.: https://github.com/gitgitgadget/git/pull/1620 And in other views it uses a red circle with what's actually a transparent x (white at the top if using light mode, gray fill if you select linux-leaks on the left, and dark gray fill in the log view): https://github.com/gitgitgadget/git/actions/runs/7265353611/job/19794849212?pr=1620 > There's an "and" vs "an" typo there, I think. I'm tempted to just > oversimplify ("...marked with red."), but am slightly concerned about > red/green color-blind folks. I suspect they'd figure it out anyway by > comparing the checkmarks (within green) to the x's (within red), but > if we want to be more detailed, perhaps we drop the "cross" altogether > and just describe it literally: "...marked with a red circle > containing a white x."? Your text aligns with what I drafted as a response but didn't send: I think it's simplest to say an `x`, or maybe "red color and an x". ``` ## Junio C Hamano, 2023-12-20 16:31 Subject: Re: [PATCH 4/8] SubmittingPatches: update extra tags list Message-ID: URL: https://gitlist.dev/e/xmqqh6kcu96z.fsf%40gitster.g In-Reply-To: <35fc350d-018a-49cf-a28e-e5ce21fe7dec@gmail.com> ``` Phillip Wood writes: > What's the difference between "Improved-by:" and "Helped-by:"? In > general I'd prefer for us not to encourage new trailers where we > already have a suitable one in use. I agree with the direction to limit the trailer tokens to common ones, as the repertoire we have sufficiently covers the needs already, and strongly discourage folks to waste their time trying to be "original". It might be useful to run stats of trailers that were used in the past, say, 3 years and that may give us a good guide to decide which ones to limit ourselves to. Thanks for reviewing. ``` ## Junio C Hamano, 2023-12-20 16:39 Subject: Re: [PATCH 6/8] SubmittingPatches: clarify GitHub visual Message-ID: URL: https://gitlist.dev/e/xmqq8r5ou8u9.fsf%40gitster.g In-Reply-To: ``` Elijah Newren writes: > ... I'm tempted to just > oversimplify ("...marked with red."), but am slightly concerned about > red/green color-blind folks. (sheepishly raises hand). Thanks for being considerate. > I suspect they'd figure it out anyway by > comparing the checkmarks (within green) to the x's (within red), I 100% agree with this. > but > if we want to be more detailed, perhaps we drop the "cross" altogether > and just describe it literally: "...marked with a red circle > containing a white x."? Thanks. ``` ## Elijah Newren, 2023-12-20 16:49 Subject: Re: [PATCH 4/8] SubmittingPatches: update extra tags list Message-ID: URL: https://gitlist.dev/e/CABPp-BFjotLN4sCe%2B6uHAU7qhr1COM0B4EdW0f0-X-xf5qXinA%40mail.gmail.com In-Reply-To: ``` On Wed, Dec 20, 2023 at 8:09 AM Josh Soref wrote: > > On Wed, Dec 20, 2023 at 10:30 AM Elijah Newren wrote: > > On Wed, Dec 20, 2023 at 7:18 AM Phillip Wood wrote: > > > Thanks for adding these, they are widely used and should be documented. > > > The patch also adds a mention for "Noticed-by:" - I'm less convinced by > > > the need for that as I explain below. > > > > > > > Updating the create suggestion to something less commonly used. > > > > > > I'm not quite sure I understand what you mean by this sentence. > > Tentatively rewritten as: > Updating the "create your own tag" suggestion as 'Mentored-by' has been > promoted. > > This commit is adding bulleted items including promoting 'Mentored-by', > which means that the suggestion of "invent your own" would really need > a new suggestion. > > Personally I'm not a fan of "invent your own", but I'm trying to > follow "when in Rome" (which is a big thing in the Git process > documentation covered by the two files subject to this series). More > on this later. Yeah, well it appears that those of us who have been here in Rome for a while aren't a fan of it anymore either; see also Junio's response in this thread about that. > > > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > > > > index 32e90238777..694a7bafb68 100644 > > > > @@ -348,6 +348,8 @@ If you like, you can put extra tags at the end: > > > > > > > > . `Reported-by:` is used to credit someone who found the bug that > > > > the patch attempts to fix. > > > > +. `Noticed-by:` liked `Reported-by:` indicates someone who noticed > > > > + the item being fixed. > > > > > > I wonder if we really need a separate "Noticed-by" footer in addition to > > > "Reported-by". Personally I use the latter to acknowledge the person who > > > reported the issue being fix regards of weather I'm fixing a bug or some > > > other issue. > > > > I'm not sure I'd mention both either; feels like we're making it hard > > for users to choose. Also, I think there's a minor distinction > > between them, but it's hard to convey simply: To me, Reported-by > > suggests someone sent a mail to the list specifically about the bug or > > issue in question. Also, to me, Noticed-by suggests that during a > > back-and-forth discussion of some sort on another topic, a fellow Git > > contributor noticed an issue and mentioned it as an aside. But, > > that's how _I_ would have used them, I didn't do any digging to find > > out if that's really how they are used. > > Given that Noticed-by is more common than Co-authored-by, I have a > hard time arguing that it shouldn't be included. Not if you look at the last three years; there Co-authored-by is more than 17 times more common than Noticed-by. > You could see that I struggled with it based on my lousy first drafts [1]. > > Anyway, tentatively: > > . `Noticed-by:` like `Reported-by:` indicates a Git contributor who > called the item (being fixed) out as an aside. > > Here, I'm struggling with the tension between "noticed-by probably > hints that something is being fixed" and "noticed-by is addressing who > suggested it and why we're attributing it to them" > > "as an aside" is itself an ellipsis for something like "as an aside to > some unrelated discussion and didn't really circle back to it as a top > level discussion point, but here we're closing the loop" -- but this > is obviously way too long-winded to be the written form Given the large drop-off in usage of the Noticed-by trailer, I'd suggest just leaving it out. > > Either way, if we're going to define them as synonyms, I'd rather we > > just left the less common one out. If there's a distinction, and it's > > not a pain to describe, then maybe it'd be worth adding both. > > > > If we do add both, though, we at least need to fix "liked" to "like" > > in your description. > > Right, it's a "first draft" [1]... :-) [...] > I personally agree. I think encouraging non-core contributors to > invent their own is not a good idea. It leads to various things > (including inconsistently cased items because users fail to review the > current set / understand them/their-construction). > > Saying that it's ok for core contributors to suggest a new tag and > that if a core contributor suggests a new tag that the person writing > the current series should just accept the tag and trust that it'll be > ok. > > Note: I'm not going to draft wording to this effect on my own, and if > I were to provide such a change, it'd be its own commit prior to the > one here, because it's a significant process change as opposed to > clarifying the list of recommended tags. Perhaps replace 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:". with 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. ? ``` ## Elijah Newren, 2023-12-20 17:00 Subject: Re: [PATCH 7/8] SubmittingPatches: clarify GitHub artifact format Message-ID: URL: https://gitlist.dev/e/CABPp-BH%2Bf_%2BhwTPF8-pivDKtFmzEyiw2NW1R9jiF24Koo1CEVw%40mail.gmail.com In-Reply-To: ``` On Wed, Dec 20, 2023 at 8:16 AM Josh Soref wrote: > > Elijah Newren wrote: > > > From: Josh Soref > > > > > > GitHub wraps artifacts generated by workflows in a .zip file. > > > > > > Internally workflows can package anything they like in them. > > > > s/Internally/Internal/? > > No, it's actually: > > s/Internally/Internally,/ > > In that, what a workflow does to structure the contents of a .zip > artifact is an implementation decision of the workflow. Ah, that makes sense with the comma; thanks. ``` ## Josh Soref, 2023-12-20 17:42 Subject: Re: [PATCH 4/8] SubmittingPatches: update extra tags list Message-ID: URL: https://gitlist.dev/e/CACZqfqCar%3Dtay5diocU7jVWBwPUFqewNYfPLHkYvvR1fSBSdPA%40mail.gmail.com In-Reply-To: ``` Elijah Newren wrote: > Yeah, well it appears that those of us who have been here in Rome for > a while aren't a fan of it anymore either; see also Junio's response > in this thread about that. Right. > [Josh Soref wrote:] > > Given that Noticed-by is more common than Co-authored-by, I have a > > hard time arguing that it shouldn't be included. > > Not if you look at the last three years; there Co-authored-by is more > than 17 times more common than Noticed-by. > Given the large drop-off in usage of the Noticed-by trailer, I'd > suggest just leaving it out. > Perhaps replace > > 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:". > > with > > 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. > > ? Let's have some fun (inception): commit eac2211332f754c5f4127a58aafb9882bfe939e8 Author: Josh Soref Date: Wed Dec 20 12:34:54 2023 -0500 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 diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 32e9023877..58dfe40504 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -358,4 +358,5 @@ If you like, you can put extra tags at the end: -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. ``` ## phillip.wood123@gmail.com, 2023-12-21 15:09 Subject: Re: [PATCH 4/8] SubmittingPatches: update extra tags list Message-ID: URL: https://gitlist.dev/e/e4b6eda6-8d20-48b3-a33d-13ee07d227ce%40gmail.com In-Reply-To: ``` Hi Josh On 20/12/2023 17:42, Josh Soref wrote: > 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 > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > index 32e9023877..58dfe40504 100644 > --- a/Documentation/SubmittingPatches > +++ b/Documentation/SubmittingPatches > @@ -358,4 +358,5 @@ If you like, you can put extra tags at the end: > > -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. Thanks for this, it looks good and would be a useful addition to v2 of your patch series. Best Wishes Phillip ``` ## Josh Soref via GitGitGadget, 2023-12-21 16:40 Subject: [PATCH v2 0/9] Minor improvements to CodingGuidelines and SubmittingPatches Message-ID: URL: https://gitlist.dev/e/pull.1623.v2.git.1703176865.gitgitgadget%40gmail.com In-Reply-To: ``` These are a bunch of things I've run into over my past couple of attempts to contribute to Git. * Incremental punctuation/grammatical improvements * Update extra tags suggestions based on common usage * drop reference to an article that was discontinued over a decade ago * update GitHub references * harmonize non-ASCII while I'm here Note that I'm trying to do things "in the neighborhood". It'll be slower than me replacing things topically, but hopefully easier for others to digest. My current estimate is a decade or two :). Josh Soref (9): CodingGuidelines: move period inside parentheses CodingGuidelines: write punctuation marks SubmittingPatches: drop ref to "What's in git.git" SubmittingPatches: discourage new trailers SubmittingPatches: update extra tags list SubmittingPatches: improve extra tags advice SubmittingPatches: clarify GitHub visual SubmittingPatches: clarify GitHub artifact format SubmittingPatches: hyphenate non-ASCII Documentation/CodingGuidelines | 4 ++-- Documentation/SubmittingPatches | 27 ++++++++++++++++++++------- 2 files changed, 22 insertions(+), 9 deletions(-) base-commit: 624eb90fa8f65a79396615f3c2842ac5a3743350 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1623%2Fjsoref%2Fdocumentation-v2 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1623/jsoref/documentation-v2 Pull-Request: https://github.com/gitgitgadget/git/pull/1623 Range-diff vs v1: 1: b9a8eb6aa4e = 1: b9a8eb6aa4e CodingGuidelines: move period inside parentheses 2: c0db8336e51 = 2: c0db8336e51 CodingGuidelines: write punctuation marks 3: 22d66c5b78a = 3: 22d66c5b78a SubmittingPatches: drop ref to "What's in git.git" 4: e5c7f29af43 ! 4: eac2211332f SubmittingPatches: update extra tags list @@ Metadata Author: Josh Soref ## Commit message ## - SubmittingPatches: update extra tags list + SubmittingPatches: discourage new trailers - Add items with at least 100 uses: - - Co-authored-by - - Helped-by - - Mentored-by - - Suggested-by - - Updating the create suggestion to something less commonly used. - - git log | - perl -ne 'next unless /^\s+[A-Z][a-z]+-\S+:/;s/^\s+//;s/:.*/:/;print'| - sort|uniq -c|sort -n|grep '[0-9][0-9] ' - 11 Helped-By: - 13 Message-ID: - 14 Reported-By: - 22 Acked-By: - 27 Inspired-by: - 29 Requested-by: - 35 Original-patch-by: - 43 Contributions-by: - 47 Signed-Off-By: - 65 Based-on-patch-by: - 68 Thanks-to: - 88 Improved-by: - 145 Co-authored-by: - 171 Noticed-by: - 182 Tested-by: - 361 Suggested-by: - 469 Mentored-by: - 1196 Reported-by: - 1727 Helped-by: - 2177 Reviewed-by: - 2202 Acked-by: - 95313 Signed-off-by: + 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 ## Documentation/SubmittingPatches ## @@ Documentation/SubmittingPatches: If you like, you can put extra tags at the end: - - . `Reported-by:` is used to credit someone who found the bug that - the patch attempts to fix. -+. `Noticed-by:` liked `Reported-by:` indicates someone who noticed -+ the item being fixed. - . `Acked-by:` says that the person who is more familiar with the area - the patch attempts to modify liked the patch. - . `Reviewed-by:`, unlike the other tags, can only be offered by the -@@ Documentation/SubmittingPatches: 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 multiple people -+ contributed to the work of a patch. -+. `Helped-by:` is used to credit someone with helping develop a -+ patch. -+. `Mentored-by:` is used to credit someone with helping develop a -+ patch. -+. `Suggested-by:` is used to credit someone with suggesting the idea -+ for a patch. - You can also create your own tag or use one that's in common usage +-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:". -+such as "Thanks-to:", "Based-on-patch-by:", or "Improved-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. -: ----------- > 5: 8848572fe2c SubmittingPatches: update extra tags list 5: 11688e4360c ! 6: 8f16c7caa73 SubmittingPatches: improve extra tags advice @@ Commit message Signed-off-by: Josh Soref ## Documentation/SubmittingPatches ## -@@ Documentation/SubmittingPatches: If you like, you can put extra tags at the end: - You can also create your own tag or use one that's in common usage - such as "Thanks-to:", "Based-on-patch-by:", or "Improved-by:". +@@ Documentation/SubmittingPatches: 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. +Extra tags should only capitalize the very first letter, i.e. favor +"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By". 6: 043d2a24202 ! 7: cdb5fd0957f SubmittingPatches: clarify GitHub visual @@ Metadata ## Commit message ## SubmittingPatches: clarify GitHub visual - Some people would expect a cross to be upright, and potentially have - unequal lengths... + 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) with containing that + object (e.g. check or x). - GitHub uses a white x overlaying a solid red circle to indicate failure. + 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. + + Using the term `cross` doesn't really help. Signed-off-by: Josh Soref 7: cdab65a4259 ! 8: 77576327df8 SubmittingPatches: clarify GitHub artifact format @@ Commit message GitHub wraps artifacts generated by workflows in a .zip file. - Internally workflows can package anything they like in them. + Internally, workflows can package anything they like in them. A recently generated failure artifact had the form: 8: 92469324813 = 9: a4878f58fe4 SubmittingPatches: hyphenate non-ASCII -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-21 16:40 Subject: [PATCH v2 1/9] CodingGuidelines: move period inside parentheses Message-ID: URL: https://gitlist.dev/e/b9a8eb6aa4e87cd96fbf2b5d514350508076d756.1703176866.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref 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 --- Documentation/CodingGuidelines | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 8ed517a5ca0..af94ed3a75d 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 -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-21 16:40 Subject: [PATCH v2 2/9] CodingGuidelines: write punctuation marks Message-ID: URL: https://gitlist.dev/e/c0db8336e519cb43767effbe842dc8b97f914a4b.1703176866.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref - Match style in Release Notes Signed-off-by: Josh Soref --- Documentation/CodingGuidelines | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index af94ed3a75d..578587a4715 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. -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-21 16:40 Subject: [PATCH v2 3/9] SubmittingPatches: drop ref to "What's in git.git" Message-ID: <22d66c5b78a6930e195141df848266cac099ca08.1703176866.git.gitgitgadget@gmail.com> URL: https://gitlist.dev/e/22d66c5b78a6930e195141df848266cac099ca08.1703176866.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref "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 --- Documentation/SubmittingPatches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index bce7f97815c..32e90238777 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]] -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-21 16:41 Subject: [PATCH v2 4/9] SubmittingPatches: discourage new trailers Message-ID: URL: https://gitlist.dev/e/eac2211332f754c5f4127a58aafb9882bfe939e8.1703176866.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref 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 --- Documentation/SubmittingPatches | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 32e90238777..58dfe405049 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. -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-21 16:41 Subject: [PATCH v2 5/9] SubmittingPatches: update extra tags list Message-ID: <8848572fe2c7432ede85e042bc2558fd8b3e8b1d.1703176866.git.gitgitgadget@gmail.com> URL: https://gitlist.dev/e/8848572fe2c7432ede85e042bc2558fd8b3e8b1d.1703176866.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref 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 --- Documentation/SubmittingPatches | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 58dfe405049..31878cb70b7 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 -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-21 16:41 Subject: [PATCH v2 6/9] SubmittingPatches: improve extra tags advice Message-ID: <8f16c7caa7366cab22ad332c402f80823add8224.1703176866.git.gitgitgadget@gmail.com> URL: https://gitlist.dev/e/8f16c7caa7366cab22ad332c402f80823add8224.1703176866.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref 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 --- Documentation/SubmittingPatches | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 31878cb70b7..4476b52a50f 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. +Extra tags should only capitalize the very first letter, 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. -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-21 16:41 Subject: [PATCH v2 7/9] SubmittingPatches: clarify GitHub visual Message-ID: URL: https://gitlist.dev/e/cdb5fd0957fee7ce8c19720f588da96898cd3dc9.1703176866.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref 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) with containing 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. Using the term `cross` doesn't really help. Signed-off-by: Josh Soref --- Documentation/SubmittingPatches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 4476b52a50f..8f79253c5cb 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -603,7 +603,7 @@ 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 ++x+. 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. -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-21 16:41 Subject: [PATCH v2 8/9] SubmittingPatches: clarify GitHub artifact format Message-ID: <77576327df8710efad73487f4be79e6801bc1fd3.1703176866.git.gitgitgadget@gmail.com> URL: https://gitlist.dev/e/77576327df8710efad73487f4be79e6801bc1fd3.1703176866.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref 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 --- Documentation/SubmittingPatches | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 8f79253c5cb..cb0dcce6a17 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -605,7 +605,8 @@ branches here: `https://github.com//git/actions/workflows/ma If a branch did not pass all test cases then it is marked with a red +x+. 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 +can also download "Artifacts" which 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 -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-21 16:41 Subject: [PATCH v2 9/9] SubmittingPatches: hyphenate non-ASCII Message-ID: URL: https://gitlist.dev/e/a4878f58fe487460bdcf94e6de08e2d03c3bfa5e.1703176866.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref Git documentation does this with the exception of ancient release notes. Signed-off-by: Josh Soref --- Documentation/SubmittingPatches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index cb0dcce6a17..9283eb0ef71 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 -- gitgitgadget ``` ## Junio C Hamano, 2023-12-21 20:57 Subject: Re: [PATCH v2 2/9] CodingGuidelines: write punctuation marks Message-ID: URL: https://gitlist.dev/e/xmqqplyzl1e8.fsf%40gitster.g In-Reply-To: ``` "Josh Soref via GitGitGadget" writes: Nobody seems to have commented on this step in the previous round, but I do not understand what you mean by ... > From: Josh Soref > > - Match style in Release Notes ... at all. The patch text is fine, though. > Signed-off-by: Josh Soref > --- > Documentation/CodingGuidelines | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines > index af94ed3a75d..578587a4715 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. ``` ## Junio C Hamano, 2023-12-21 21:03 Subject: Re: [PATCH v2 1/9] CodingGuidelines: move period inside parentheses Message-ID: URL: https://gitlist.dev/e/xmqqedffl13r.fsf%40gitster.g In-Reply-To: ``` "Josh Soref via GitGitGadget" writes: > From: Josh Soref > > 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. Nobody seems to have commented on this one in the previous round, but quite honestly, for this particular instance, I suspect that it may become easier to read if we just lost these parentheses, as the next sentence "You do not have to include more than ..." is just a bit of extra material to support the first sentence like the one we see in the parentheses. Alternatively, moving that "You do not have to" also inside the same parentheses might work slightly better. It might be even easier to follow if we moved the list of "approved headers" (and the "You do not have to ... more than one" note that supports the "currently approved list") totally out of line by making it a side note. > Signed-off-by: Josh Soref > --- > Documentation/CodingGuidelines | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines > index 8ed517a5ca0..af94ed3a75d 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 ``` ## Junio C Hamano, 2023-12-21 21:09 Subject: Re: [PATCH v2 3/9] SubmittingPatches: drop ref to "What's in git.git" Message-ID: URL: https://gitlist.dev/e/xmqqa5q3l0tn.fsf%40gitster.g In-Reply-To: <22d66c5b78a6930e195141df848266cac099ca08.1703176866.git.gitgitgadget@gmail.com> ``` "Josh Soref via GitGitGadget" writes: > From: Josh Soref > > "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 > --- > Documentation/SubmittingPatches | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) Thanks. I stopped doing these long time ago, as there were certain overlaps with "What's cooking" that lists the topics that have graduated in a separate section. > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > index bce7f97815c..32e90238777 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]] ``` ## Junio C Hamano, 2023-12-21 21:16 Subject: Re: [PATCH v2 5/9] SubmittingPatches: update extra tags list Message-ID: URL: https://gitlist.dev/e/xmqq4jgbl0iz.fsf%40gitster.g In-Reply-To: <8848572fe2c7432ede85e042bc2558fd8b3e8b1d.1703176866.git.gitgitgadget@gmail.com> ``` "Josh Soref via GitGitGadget" writes: > +. `Co-authored-by:` is used to indicate that people exchanged drafts > + of a patch before submitting it. I am afraid this misses the essence of what Co-authoring means. You may have shared your draft as FYI to your colleagues, and they may have tweaked phrasing and responded with their reviews to help you improve _your_ work, but that may not make them your Co-authors. I think the "intent" counts more. If people closely worked together, exchanging drafts and agreeing on the final version among themselves before submitting, with the understanding that they share the authorship credit/blame, they are Co-authors. > +. `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). Nicely differentiated. ``` ## Junio C Hamano, 2023-12-21 21:18 Subject: Re: [PATCH v2 6/9] SubmittingPatches: improve extra tags advice Message-ID: URL: https://gitlist.dev/e/xmqqzfy3jlv1.fsf%40gitster.g In-Reply-To: <8f16c7caa7366cab22ad332c402f80823add8224.1703176866.git.gitgitgadget@gmail.com> ``` "Josh Soref via GitGitGadget" writes: > From: Josh Soref > > 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 > --- > Documentation/SubmittingPatches | 3 +++ > 1 file changed, 3 insertions(+) > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > index 31878cb70b7..4476b52a50f 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. > > +Extra tags should only capitalize the very first letter, i.e. favor > +"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By". Drop "Extra", perhaps? The sentence before already discourages any extra ones, and what this sentence teaches the contributors is to avoud spelling variation when to spell the common ones. > [[git-tools]] > === Generate your patch using Git tools out of your commits. ``` ## Junio C Hamano, 2023-12-21 21:27 Subject: Re: [PATCH v2 7/9] SubmittingPatches: clarify GitHub visual Message-ID: URL: https://gitlist.dev/e/xmqqv88rjleu.fsf%40gitster.g In-Reply-To: ``` "Josh Soref via GitGitGadget" writes: > From: Josh Soref > > 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) with containing 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. > > Using the term `cross` doesn't really help. I am not sure if this is accurate. Using `x` alone does not help, either. I think this was raised during the review of the initial round, but ... > 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 > ++x+. In that case you can click on the failing job and navigate to ... it would help if we added something like ", instead of a green checkmark" after "with a red x". It will make the contrast with the succeeding case stronger. IOW, we can take advantage of the idea to use "pair with distinct shapes and colors" ourselves. > "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. ``` ## Josh Soref, 2023-12-21 21:46 Subject: Re: [PATCH v2 2/9] CodingGuidelines: write punctuation marks Message-ID: URL: https://gitlist.dev/e/CACZqfqAtT_M8T3AxbgZrkgi3GtQ%3DJZLu4wvh3O0C9dFvCU3rWg%40mail.gmail.com In-Reply-To: ``` Junio C Hamano wrote: > Nobody seems to have commented on this step in the previous round, > but I do not understand what you mean by ... > > > From: Josh Soref > > - Match style in Release Notes > > ... at all. The patch text is fine, though. https://github.com/gitgitgadget/git/blob/692be87cbba55e8488f805d236f2ad50483bd7d5/Documentation/RelNotes/2.43.0.txt#L221 ``` ## Josh Soref, 2023-12-21 21:52 Subject: Re: [PATCH v2 1/9] CodingGuidelines: move period inside parentheses Message-ID: URL: https://gitlist.dev/e/CACZqfqCzJf5q2xcfPT3C0YAWS0qNxyQvYikisDokQ5Dw-ZFMww%40mail.gmail.com In-Reply-To: ``` Junio C Hamano wrote: > > From: Josh Soref > > > > 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. > > Nobody seems to have commented on this one in the previous round, > but quite honestly, for this particular instance, I suspect that it > may become easier to read if we just lost these parentheses, as the > next sentence "You do not have to include more than ..." is just a > bit of extra material to support the first sentence like the one we > see in the parentheses. Alternatively, moving that "You do not have > to" also inside the same parentheses might work slightly better. > It might be even easier to follow if we moved the list of "approved > headers" (and the "You do not have to ... more than one" note that > supports the "currently approved list") totally out of line by > making it a side note. I think, in principle, it'd be better if it was its own thing, but the structure of this entire section makes this really hard -- I certainly can't imagine a way to do it. The laziest fix is: - The first #include in C files, except in platform specific compat/ implementations and sha1dc/, must be one of "git-compat-util.h", "builtin.h", "t/helper/test-tool.h", "xdiff/xinclude.h", or "reftable/system.h". Beyond that, I don't understand how to parse: You do not have to include more than one of these. (Sorry, I'd like to be slightly ignorant of the C parts of git -- let's ignore that I've been blamed for at least one change to them -- so, I'm not going to look.) ``` ## Josh Soref, 2023-12-21 21:55 Subject: Re: [PATCH v2 5/9] SubmittingPatches: update extra tags list Message-ID: URL: https://gitlist.dev/e/CACZqfqBWKepr7A2O8Wp_8FqD5h9%3DO6kQUqEjN8Z1fOdks1TYPA%40mail.gmail.com In-Reply-To: ``` Junio C Hamano wrote: > "Josh Soref via GitGitGadget" writes: > > > +. `Co-authored-by:` is used to indicate that people exchanged drafts > > + of a patch before submitting it. > > I am afraid this misses the essence of what Co-authoring means. > You may have shared your draft as FYI to your colleagues, and they > may have tweaked phrasing and responded with their reviews to help > you improve _your_ work, but that may not make them your Co-authors. > > I think the "intent" counts more. If people closely worked > together, exchanging drafts and agreeing on the final version among > themselves before submitting, with the understanding that they share > the authorship credit/blame, they are Co-authors. . `Co-authored-by:` is used to indicate that people collaborated on the contents of a patch before submitting it. ? ``` ## Junio C Hamano, 2023-12-21 21:57 Subject: Re: [PATCH v2 2/9] CodingGuidelines: write punctuation marks Message-ID: URL: https://gitlist.dev/e/xmqqr0jfjk1s.fsf%40gitster.g In-Reply-To: ``` Josh Soref writes: > Junio C Hamano wrote: >> Nobody seems to have commented on this step in the previous round, >> but I do not understand what you mean by ... >> >> > From: Josh Soref >> > - Match style in Release Notes >> >> ... at all. The patch text is fine, though. > > https://github.com/gitgitgadget/git/blob/692be87cbba55e8488f805d236f2ad50483bd7d5/Documentation/RelNotes/2.43.0.txt#L221 You mean just a single mention of the phrase? If so, you should pinpoint it, e.g. "The release notes for Git 2.43 calls them 'punctuation marks', so let's use that here, too" or something like that. Unless you are sure that all the issues of Release Notes have and will consistently say "punctuation marks" and never say "punctuations", that is. ``` ## Dragan Simic, 2023-12-22 01:30 Subject: Re: [PATCH v2 1/9] CodingGuidelines: move period inside parentheses Message-ID: URL: https://gitlist.dev/e/b3b03da0e33b805f1f420a0dc1a19d86%40manjaro.org In-Reply-To: ``` On 2023-12-21 22:03, Junio C Hamano wrote: > "Josh Soref via GitGitGadget" writes: > >> From: Josh Soref >> >> 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. > > Nobody seems to have commented on this one in the previous round, > but quite honestly, for this particular instance, I suspect that it > may become easier to read if we just lost these parentheses, as the > next sentence "You do not have to include more than ..." is just a > bit of extra material to support the first sentence like the one we > see in the parentheses. Alternatively, moving that "You do not have > to" also inside the same parentheses might work slightly better. I agree with simply erasing the parentheses, it makes the paragraph flow much better. > It might be even easier to follow if we moved the list of "approved > headers" (and the "You do not have to ... more than one" note that > supports the "currently approved list") totally out of line by > making it a side note. > >> Signed-off-by: Josh Soref >> --- >> Documentation/CodingGuidelines | 2 +- >> 1 file changed, 1 insertion(+), 1 deletion(-) >> >> diff --git a/Documentation/CodingGuidelines >> b/Documentation/CodingGuidelines >> index 8ed517a5ca0..af94ed3a75d 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 ``` ## Josh Soref via GitGitGadget, 2023-12-28 04:55 Subject: [PATCH v3 0/9] Minor improvements to CodingGuidelines and SubmittingPatches Message-ID: URL: https://gitlist.dev/e/pull.1623.v3.git.1703739324.gitgitgadget%40gmail.com In-Reply-To: ``` These are a bunch of things I've run into over my past couple of attempts to contribute to Git. * Incremental punctuation/grammatical improvements * Update extra tags suggestions based on common usage * drop reference to an article that was discontinued over a decade ago * update GitHub references * harmonize non-ASCII while I'm here Note that I'm trying to do things "in the neighborhood". It'll be slower than me replacing things topically, but hopefully easier for others to digest. My current estimate is a decade or two :). Josh Soref (9): CodingGuidelines: move period inside parentheses CodingGuidelines: write punctuation marks SubmittingPatches: drop ref to "What's in git.git" SubmittingPatches: discourage new trailers SubmittingPatches: update extra tags list SubmittingPatches: provide tag naming advice SubmittingPatches: clarify GitHub visual SubmittingPatches: clarify GitHub artifact format SubmittingPatches: hyphenate non-ASCII Documentation/CodingGuidelines | 4 ++-- Documentation/SubmittingPatches | 33 +++++++++++++++++++++++---------- 2 files changed, 25 insertions(+), 12 deletions(-) base-commit: 624eb90fa8f65a79396615f3c2842ac5a3743350 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1623%2Fjsoref%2Fdocumentation-v3 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1623/jsoref/documentation-v3 Pull-Request: https://github.com/gitgitgadget/git/pull/1623 Range-diff vs v2: 1: b9a8eb6aa4e = 1: b9a8eb6aa4e CodingGuidelines: move period inside parentheses 2: c0db8336e51 = 2: c0db8336e51 CodingGuidelines: write punctuation marks 3: 22d66c5b78a = 3: 22d66c5b78a SubmittingPatches: drop ref to "What's in git.git" 4: eac2211332f = 4: eac2211332f SubmittingPatches: discourage new trailers 5: 8848572fe2c = 5: 8848572fe2c SubmittingPatches: update extra tags list 6: 8f16c7caa73 ! 6: f28c1011ba9 SubmittingPatches: improve extra tags advice @@ Metadata Author: Josh Soref ## Commit message ## - SubmittingPatches: improve extra tags advice + 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: @@ Documentation/SubmittingPatches: While you can also create your own trailer if t encourage you to instead use one of the common trailers in this project highlighted above. -+Extra tags should only capitalize the very first letter, i.e. favor ++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]] 7: cdb5fd0957f < -: ----------- SubmittingPatches: clarify GitHub visual 8: 77576327df8 ! 7: 49cef6f7c20 SubmittingPatches: clarify GitHub artifact format @@ Metadata Author: Josh Soref ## Commit message ## - SubmittingPatches: clarify GitHub artifact format + SubmittingPatches: clarify GitHub visual - GitHub wraps artifacts generated by workflows in a .zip file. + 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). - 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 + 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 ## Documentation/SubmittingPatches ## -@@ Documentation/SubmittingPatches: branches here: `https://github.com//git/actions/workflows/ma - If a branch did not pass all test cases then it is marked with a red - +x+. 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 +@@ Documentation/SubmittingPatches: 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 -+can also download "Artifacts" which are zip archives containing -+tarred (or zipped) archives - with test data relevant for debugging. +-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. -: ----------- > 8: deb1bf02f3a SubmittingPatches: clarify GitHub artifact format 9: a4878f58fe4 = 9: b1b75cc6a3e SubmittingPatches: hyphenate non-ASCII -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-28 04:55 Subject: [PATCH v3 1/9] CodingGuidelines: move period inside parentheses Message-ID: URL: https://gitlist.dev/e/b9a8eb6aa4e87cd96fbf2b5d514350508076d756.1703739324.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref 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 --- Documentation/CodingGuidelines | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 8ed517a5ca0..af94ed3a75d 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 -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-28 04:55 Subject: [PATCH v3 2/9] CodingGuidelines: write punctuation marks Message-ID: URL: https://gitlist.dev/e/c0db8336e519cb43767effbe842dc8b97f914a4b.1703739324.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref - Match style in Release Notes Signed-off-by: Josh Soref --- Documentation/CodingGuidelines | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index af94ed3a75d..578587a4715 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. -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-28 04:55 Subject: [PATCH v3 3/9] SubmittingPatches: drop ref to "What's in git.git" Message-ID: <22d66c5b78a6930e195141df848266cac099ca08.1703739324.git.gitgitgadget@gmail.com> URL: https://gitlist.dev/e/22d66c5b78a6930e195141df848266cac099ca08.1703739324.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref "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 --- Documentation/SubmittingPatches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index bce7f97815c..32e90238777 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]] -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-28 04:55 Subject: [PATCH v3 4/9] SubmittingPatches: discourage new trailers Message-ID: URL: https://gitlist.dev/e/eac2211332f754c5f4127a58aafb9882bfe939e8.1703739324.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref 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 --- Documentation/SubmittingPatches | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 32e90238777..58dfe405049 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. -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-28 04:55 Subject: [PATCH v3 5/9] SubmittingPatches: update extra tags list Message-ID: <8848572fe2c7432ede85e042bc2558fd8b3e8b1d.1703739324.git.gitgitgadget@gmail.com> URL: https://gitlist.dev/e/8848572fe2c7432ede85e042bc2558fd8b3e8b1d.1703739324.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref 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 --- Documentation/SubmittingPatches | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 58dfe405049..31878cb70b7 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 -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-28 04:55 Subject: [PATCH v3 6/9] SubmittingPatches: provide tag naming advice Message-ID: URL: https://gitlist.dev/e/f28c1011ba91ce6ddcf09346c59cbc2b06c68ffc.1703739324.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref 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 --- Documentation/SubmittingPatches | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 31878cb70b7..94c874ab5e6 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. -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-28 04:55 Subject: [PATCH v3 7/9] SubmittingPatches: clarify GitHub visual Message-ID: <49cef6f7c20d79ef217b345364ce9f7143bf7b7d.1703739324.git.gitgitgadget@gmail.com> URL: https://gitlist.dev/e/49cef6f7c20d79ef217b345364ce9f7143bf7b7d.1703739324.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref 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 --- Documentation/SubmittingPatches | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 94c874ab5e6..0665f89f38c 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. -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-28 04:55 Subject: [PATCH v3 8/9] SubmittingPatches: clarify GitHub artifact format Message-ID: URL: https://gitlist.dev/e/deb1bf02f3a3b0977f22a0f2d9ff4b84ad3ad5f3.1703739324.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref 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 --- Documentation/SubmittingPatches | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 0665f89f38c..5e2e13b5e09 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. -- gitgitgadget ``` ## Josh Soref via GitGitGadget, 2023-12-28 04:55 Subject: [PATCH v3 9/9] SubmittingPatches: hyphenate non-ASCII Message-ID: URL: https://gitlist.dev/e/b1b75cc6a3e4b6829a60550b394456dcb2a6ee25.1703739324.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Josh Soref Git documentation does this with the exception of ancient release notes. Signed-off-by: Josh Soref --- Documentation/SubmittingPatches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 5e2e13b5e09..e734a3f0f17 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 -- gitgitgadget ```