{"thread":{"id":"60631","subject":"[PATCH 0/8] Minor improvements to CodingGuidelines and SubmittingPatches","startedAt":"2023-12-19T08:42:03Z","lastAt":"2023-12-28T04:55:37Z","messageCount":55,"participants":["Josh Soref via GitGitGadget","René Scharfe","Phillip Wood","Elijah Newren","Josh Soref","Junio C Hamano","phillip.wood123@gmail.com","Dragan Simic"],"isPatch":true,"patchVersion":1,"patchTotal":8},"messages":[{"id":"485799","messageId":"pull.1623.git.1702975319.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":null,"subject":"[PATCH 0/8] Minor improvements to CodingGuidelines and SubmittingPatches","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-19T08:41:51Z","receivedAt":"2023-12-19T08:42:03Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"These are a bunch of things I've run into over my past couple of attempts to\ncontribute to Git.\n\n * Incremental punctuation/grammatical improvements\n * Update extra tags suggestions based on common usage\n * drop reference to an article that was discontinued over a decade ago\n * update GitHub references\n * harmonize non-ASCII while I'm here\n\nNote that I'm trying to do things \"in the neighborhood\". It'll be slower\nthan me replacing things topically, but hopefully easier for others to\ndigest. My current estimate is a decade or two :).\n\nJosh Soref (8):\n CodingGuidelines: move period inside parentheses\n CodingGuidelines: write punctuation marks\n SubmittingPatches: drop ref to \"What's in git.git\"\n SubmittingPatches: update extra tags list\n SubmittingPatches: improve extra tags advice\n SubmittingPatches: clarify GitHub visual\n SubmittingPatches: clarify GitHub artifact format\n SubmittingPatches: hyphenate non-ASCII\n\n Documentation/CodingGuidelines | 4 ++--\n Documentation/SubmittingPatches | 24 +++++++++++++++++++-----\n 2 files changed, 21 insertions(+), 7 deletions(-)\n\n\nbase-commit: 624eb90fa8f65a79396615f3c2842ac5a3743350\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1623%2Fjsoref%2Fdocumentation-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1623/jsoref/documentation-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1623\n-- \ngitgitgadget\n"},{"id":"485800","messageId":"b9a8eb6aa4e87cd96fbf2b5d514350508076d756.1702975319.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.git.1702975319.gitgitgadget@gmail.com","subject":"[PATCH 1/8] CodingGuidelines: move period inside parentheses","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-19T08:41:52Z","receivedAt":"2023-12-19T08:42:03Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nThe contents within parenthesis should be omittable without resulting\nin broken text.\n\nEliding the parenthesis left a period to end a run without any content.\n\nSigned-off-by: Josh Soref \n---\n Documentation/CodingGuidelines | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 8ed517a5ca0..af94ed3a75d 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -450,7 +450,7 @@ For C programs:\n one of the approved headers that includes it first for you. (The\n approved headers currently include \"builtin.h\",\n \"t/helper/test-tool.h\", \"xdiff/xinclude.h\", or\n- \"reftable/system.h\"). You do not have to include more than one of\n+ \"reftable/system.h\".) You do not have to include more than one of\n these.\n \n - A C file must directly include the header files that declare the\n-- \ngitgitgadget\n\n"},{"id":"485801","messageId":"c0db8336e519cb43767effbe842dc8b97f914a4b.1702975319.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.git.1702975319.gitgitgadget@gmail.com","subject":"[PATCH 2/8] CodingGuidelines: write punctuation marks","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-19T08:41:53Z","receivedAt":"2023-12-19T08:42:04Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\n- Match style in Release Notes\n\nSigned-off-by: Josh Soref \n---\n Documentation/CodingGuidelines | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex af94ed3a75d..578587a4715 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -578,7 +578,7 @@ Externally Visible Names\n . The variable name describes the effect of tweaking this knob.\n \n The section and variable names that consist of multiple words are\n- formed by concatenating the words without punctuations (e.g. `-`),\n+ formed by concatenating the words without punctuation marks (e.g. `-`),\n and are broken using bumpyCaps in documentation as a hint to the\n reader.\n \n-- \ngitgitgadget\n\n"},{"id":"485802","messageId":"22d66c5b78a6930e195141df848266cac099ca08.1702975320.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.git.1702975319.gitgitgadget@gmail.com","subject":"[PATCH 3/8] SubmittingPatches: drop ref to \"What's in git.git\"","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-19T08:41:54Z","receivedAt":"2023-12-19T08:42:05Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\n\"What's in git.git\" was last seen in 2010:\n https://lore.kernel.org/git/?q=%22what%27s+in+git.git%22\n https://lore.kernel.org/git/7vaavikg72.fsf@alter.siamese.dyndns.org/\n\nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex bce7f97815c..32e90238777 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -570,7 +570,7 @@ their trees themselves.\n master).\n \n * Read the Git mailing list, the maintainer regularly posts messages\n- entitled \"What's cooking in git.git\" and \"What's in git.git\" giving\n+ entitled \"What's cooking in git.git\" giving\n the status of various proposed changes.\n \n == GitHub CI[[GHCI]]\n-- \ngitgitgadget\n\n"},{"id":"485803","messageId":"e5c7f29af439c48f59b2f35af93a7972e66a5b6b.1702975320.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.git.1702975319.gitgitgadget@gmail.com","subject":"[PATCH 4/8] SubmittingPatches: update extra tags list","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-19T08:41:55Z","receivedAt":"2023-12-19T08:42:06Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nAdd items with at least 100 uses:\n- Co-authored-by\n- Helped-by\n- Mentored-by\n- Suggested-by\n\nUpdating the create suggestion to something less commonly used.\n\ngit log |\n perl -ne 'next unless /^\\s+[A-Z][a-z]+-\\S+:/;s/^\\s+//;s/:.*/:/;print'|\n sort|uniq -c|sort -n|grep '[0-9][0-9] '\n 11 Helped-By:\n 13 Message-ID:\n 14 Reported-By:\n 22 Acked-By:\n 27 Inspired-by:\n 29 Requested-by:\n 35 Original-patch-by:\n 43 Contributions-by:\n 47 Signed-Off-By:\n 65 Based-on-patch-by:\n 68 Thanks-to:\n 88 Improved-by:\n 145 Co-authored-by:\n 171 Noticed-by:\n 182 Tested-by:\n 361 Suggested-by:\n 469 Mentored-by:\n1196 Reported-by:\n1727 Helped-by:\n2177 Reviewed-by:\n2202 Acked-by:\n95313 Signed-off-by:\n\nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 12 +++++++++++-\n 1 file changed, 11 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 32e90238777..694a7bafb68 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -348,6 +348,8 @@ If you like, you can put extra tags at the end:\n \n . `Reported-by:` is used to credit someone who found the bug that\n the patch attempts to fix.\n+. `Noticed-by:` liked `Reported-by:` indicates someone who noticed\n+ the item being fixed.\n . `Acked-by:` says that the person who is more familiar with the area\n the patch attempts to modify liked the patch.\n . `Reviewed-by:`, unlike the other tags, can only be offered by the\n@@ -355,9 +357,17 @@ If you like, you can put extra tags at the end:\n patch after a detailed analysis.\n . `Tested-by:` is used to indicate that the person applied the patch\n and found it to have the desired effect.\n+. `Co-authored-by:` is used to indicate that multiple people\n+ contributed to the work of a patch.\n+. `Helped-by:` is used to credit someone with helping develop a\n+ patch.\n+. `Mentored-by:` is used to credit someone with helping develop a\n+ patch.\n+. `Suggested-by:` is used to credit someone with suggesting the idea\n+ for a patch.\n \n You can also create your own tag or use one that's in common usage\n-such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Mentored-by:\".\n+such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Improved-by:\".\n \n [[git-tools]]\n === Generate your patch using Git tools out of your commits.\n-- \ngitgitgadget\n\n"},{"id":"485804","messageId":"11688e4360c1698e56b3485e3df4e171397d3c3c.1702975320.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.git.1702975319.gitgitgadget@gmail.com","subject":"[PATCH 5/8] SubmittingPatches: improve extra tags advice","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-19T08:41:56Z","receivedAt":"2023-12-19T08:42:07Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nCurrent statistics show a strong preference to only capitalize the first\nletter in a hyphenated tag, but that some guidance would be helpful:\n\ngit log |\n perl -ne 'next unless /^\\s+(?:Signed-[oO]ff|Acked)-[bB]y:/;\n s/^\\s+//;s/:.*/:/;print'|\n sort|uniq -c|sort -n\n 2 Signed-off-By:\n 4 Signed-Off-by:\n 22 Acked-By:\n 47 Signed-Off-By:\n2202 Acked-by:\n95315 Signed-off-by:\n\nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 694a7bafb68..d7a84f59478 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -369,6 +369,9 @@ If you like, you can put extra tags at the end:\n You can also create your own tag or use one that's in common usage\n such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Improved-by:\".\n \n+Extra tags should only capitalize the very first letter, i.e. favor\n+\"Signed-off-by\" over \"Signed-Off-By\" and \"Acked-by:\" over \"Acked-By\".\n+\n [[git-tools]]\n === Generate your patch using Git tools out of your commits.\n \n-- \ngitgitgadget\n\n"},{"id":"485805","messageId":"043d2a24202d39c5564e4a4369c86ae4648dd721.1702975320.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.git.1702975319.gitgitgadget@gmail.com","subject":"[PATCH 6/8] SubmittingPatches: clarify GitHub visual","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-19T08:41:57Z","receivedAt":"2023-12-19T08:42:08Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nSome people would expect a cross to be upright, and potentially have\nunequal lengths...\n\nGitHub uses a white x overlaying a solid red circle to indicate failure.\n\nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex d7a84f59478..8e19c7f82e4 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -604,7 +604,7 @@ to your fork of Git on GitHub. You can monitor the test state of all your\n branches here: `https://github.com//git/actions/workflows/main.yml`\n \n If a branch did not pass all test cases then it is marked with a red\n-cross. In that case you can click on the failing job and navigate to\n++x+. In that case you can click on the failing job and navigate to\n \"ci/run-build-and-tests.sh\" and/or \"ci/print-test-failures.sh\". You\n can also download \"Artifacts\" which are tarred (or zipped) archives\n with test data relevant for debugging.\n-- \ngitgitgadget\n\n"},{"id":"485806","messageId":"cdab65a425944e9d10f6aa6be378162cd5450c81.1702975320.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.git.1702975319.gitgitgadget@gmail.com","subject":"[PATCH 7/8] SubmittingPatches: clarify GitHub artifact format","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-19T08:41:58Z","receivedAt":"2023-12-19T08:42:09Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nGitHub wraps artifacts generated by workflows in a .zip file.\n\nInternally workflows can package anything they like in them.\n\nA recently generated failure artifact had the form:\n\nwindows-artifacts.zip\n Length Date Time Name\n--------- ---------- ----- ----\n 76001695 12-19-2023 01:35 artifacts.tar.gz\n 11005650 12-19-2023 01:35 tracked.tar.gz\n--------- -------\n 87007345 2 files\n\nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 8e19c7f82e4..b4fa52ae348 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -606,7 +606,8 @@ branches here: `https://github.com//git/actions/workflows/ma\n If a branch did not pass all test cases then it is marked with a red\n +x+. In that case you can click on the failing job and navigate to\n \"ci/run-build-and-tests.sh\" and/or \"ci/print-test-failures.sh\". You\n-can also download \"Artifacts\" which are tarred (or zipped) archives\n+can also download \"Artifacts\" which are zip archives containing\n+tarred (or zipped) archives\n with test data relevant for debugging.\n \n Then fix the problem and push your fix to your GitHub fork. This will\n-- \ngitgitgadget\n\n"},{"id":"485807","messageId":"92469324813702418a9db0b2e760580518b225cd.1702975320.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.git.1702975319.gitgitgadget@gmail.com","subject":"[PATCH 8/8] SubmittingPatches: hyphenate non-ASCII","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-19T08:41:59Z","receivedAt":"2023-12-19T08:42:10Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nGit documentation does this with the exception of ancient release notes.\n\nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex b4fa52ae348..3c53592cfc8 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -700,7 +700,7 @@ message to an external program, and this is a handy way to drive\n `git am`. However, if the message is MIME encoded, what is\n piped into the program is the representation you see in your\n `*Article*` buffer after unwrapping MIME. This is often not what\n-you would want for two reasons. It tends to screw up non ASCII\n+you would want for two reasons. It tends to screw up non-ASCII\n characters (most notably in people's names), and also\n whitespaces (fatal in patches). Running \"C-u g\" to display the\n message in raw form before using \"|\" to run the pipe can work\n-- \ngitgitgadget\n"},{"id":"485814","messageId":"e788cf7b-56c7-48c2-ad4f-65d9c9e73ad5@web.de","threadId":"60631","inReplyTo":"043d2a24202d39c5564e4a4369c86ae4648dd721.1702975320.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 6/8] SubmittingPatches: clarify GitHub visual","fromName":"René Scharfe","fromEmail":"l.s.r@web.de","sentAt":"2023-12-19T14:44:30Z","receivedAt":"2023-12-19T14:44:32Z","isPatch":true,"sender":{"key":"l.s.r@web.de","avatar":"https://avatars.githubusercontent.com/u/26122331?v=4"},"body":"Am 19.12.23 um 09:41 schrieb Josh Soref via GitGitGadget:\n> From: Josh Soref \n>\n> Some people would expect a cross to be upright, and potentially have\n> unequal lengths...\n\nThere are lots of types of crosses. And while looking them up on\nWikipedia I learned today that an x-cross is called \"saltire\" in\nEnglish. I only knew it as St. Andrew's cross before.\n\n> GitHub uses a white x overlaying a solid red circle to indicate failure.\n\nThey call it \"x-circle-fill\"\n(https://primer.github.io/octicons/x-circle-fill-16).\n\n>\n> Signed-off-by: Josh Soref \n> ---\n> Documentation/SubmittingPatches | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> index d7a84f59478..8e19c7f82e4 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -604,7 +604,7 @@ to your fork of Git on GitHub. You can monitor the test state of all your\n> branches here: `https://github.com//git/actions/workflows/main.yml`\n>\n> If a branch did not pass all test cases then it is marked with a red\n> -cross. In that case you can click on the failing job and navigate to\n> ++x+. In that case you can click on the failing job and navigate to\n\nIn the commit message you say the x is white, here it's red, so what is\nit? IIUC the circle is red and the x-cross inside is the same color as\nthe background, i.e. white in light mode and black in dark mode. No\nidea how to express that in one word. Perhaps \"red circle containing\nand x-cross\"?\n\nRené\n\n"},{"id":"485862","messageId":"35fc350d-018a-49cf-a28e-e5ce21fe7dec@gmail.com","threadId":"60631","inReplyTo":"e5c7f29af439c48f59b2f35af93a7972e66a5b6b.1702975320.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 4/8] SubmittingPatches: update extra tags list","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2023-12-20T15:18:20Z","receivedAt":"2023-12-20T15:18:23Z","isPatch":true,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"Hi Josh\n\nOn 19/12/2023 08:41, Josh Soref via GitGitGadget wrote:\n> From: Josh Soref \n> \n> Add items with at least 100 uses:\n> - Co-authored-by\n> - Helped-by\n> - Mentored-by\n> - Suggested-by\n\nThanks for adding these, they are widely used and should be documented. \nThe patch also adds a mention for \"Noticed-by:\" - I'm less convinced by \nthe need for that as I explain below.\n\n> Updating the create suggestion to something less commonly used.\n\nI'm not quite sure I understand what you mean by this sentence.\n\n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> index 32e90238777..694a7bafb68 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -348,6 +348,8 @@ If you like, you can put extra tags at the end:\n> \n> . `Reported-by:` is used to credit someone who found the bug that\n> the patch attempts to fix.\n> +. `Noticed-by:` liked `Reported-by:` indicates someone who noticed\n> + the item being fixed.\n\nI wonder if we really need a separate \"Noticed-by\" footer in addition to \n\"Reported-by\". Personally I use the latter to acknowledge the person who \nreported the issue being fix regards of weather I'm fixing a bug or some \nother issue.\n\n> . `Acked-by:` says that the person who is more familiar with the area\n> the patch attempts to modify liked the patch.\n> . `Reviewed-by:`, unlike the other tags, can only be offered by the\n> @@ -355,9 +357,17 @@ If you like, you can put extra tags at the end:\n> patch after a detailed analysis.\n> . `Tested-by:` is used to indicate that the person applied the patch\n> and found it to have the desired effect.\n> +. `Co-authored-by:` is used to indicate that multiple people\n> + contributed to the work of a patch.\n\nJunio's comments in [1] may be helpful here\n\n If co-authors closely worked together (possibly but not necessarily\n outside the public view), exchanging drafts and agreeing on the\n final version before sending it to the list, by one approving the\n other's final draft, Co-authored-by may be appropriate.\n\n I would prefer to see more use of Helped-by when suggestions for\n improvements were made, possibly but not necessarily in a concrete\n \"squashable patch\" form, the original author accepted before\n sending the new version out, and the party who made suggestions saw\n the updated version at the same time as the general public.\n\nSo I think we should be clear that \"Co-authored-by:\" means that multiple \nauthors worked closely together on the patch, rather than just \ncontributed to it.\n\n[1] https://lore.kernel.org/git/xmqqmth8wwcf.fsf@gitster.g/\n\n> +. `Helped-by:` is used to credit someone with helping develop a\n> + patch.\n> +. `Mentored-by:` is used to credit someone with helping develop a\n> + patch.\n\nI think we use \"Montored-by:\" specifically to credit the mentor on \npatches written by GSoC or Outreachy interns and \"Helped-by:\" for the \ngeneral case of someone helping the patch author.\n\n> +. `Suggested-by:` is used to credit someone with suggesting the idea\n> + for a patch.\n> \n> You can also create your own tag or use one that's in common usage\n> -such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Mentored-by:\".\n> +such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Improved-by:\".\n\nWhat's the difference between \"Improved-by:\" and \"Helped-by:\"? In \ngeneral I'd prefer for us not to encourage new trailers where we already \nhave a suitable one in use.\n\nThanks for working on this, it will be good to have better descriptions \nof our common trailers.\n\nBest Wishes\n\nPhillip\n"},{"id":"485863","messageId":"CABPp-BFbLN7dsKvm+___y6s8OWARhXB5BHq5N3sKWaf66RPzDg@mail.gmail.com","threadId":"60631","inReplyTo":"cdab65a425944e9d10f6aa6be378162cd5450c81.1702975320.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 7/8] SubmittingPatches: clarify GitHub artifact format","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2023-12-20T15:21:47Z","receivedAt":"2023-12-20T15:22:01Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Tue, Dec 19, 2023 at 12:42 AM Josh Soref via GitGitGadget\n wrote:\n>\n> From: Josh Soref \n>\n> GitHub wraps artifacts generated by workflows in a .zip file.\n>\n> Internally workflows can package anything they like in them.\n\ns/Internally/Internal/?\n\n>\n> A recently generated failure artifact had the form:\n>\n> windows-artifacts.zip\n> Length Date Time Name\n> --------- ---------- ----- ----\n> 76001695 12-19-2023 01:35 artifacts.tar.gz\n> 11005650 12-19-2023 01:35 tracked.tar.gz\n> --------- -------\n> 87007345 2 files\n>\n> Signed-off-by: Josh Soref \n> ---\n> Documentation/SubmittingPatches | 3 ++-\n> 1 file changed, 2 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> index 8e19c7f82e4..b4fa52ae348 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -606,7 +606,8 @@ branches here: `https://github.com//git/actions/workflows/ma\n> If a branch did not pass all test cases then it is marked with a red\n> +x+. In that case you can click on the failing job and navigate to\n> \"ci/run-build-and-tests.sh\" and/or \"ci/print-test-failures.sh\". You\n> -can also download \"Artifacts\" which are tarred (or zipped) archives\n> +can also download \"Artifacts\" which are zip archives containing\n> +tarred (or zipped) archives\n> with test data relevant for debugging.\n>\n> Then fix the problem and push your fix to your GitHub fork. This will\n> --\n> gitgitgadget\n>\n"},{"id":"485865","messageId":"CABPp-BH_iP2KjPi-5kW8ROQWfy8XoUmbGhyT-Y1dZGtCtZXQGQ@mail.gmail.com","threadId":"60631","inReplyTo":"35fc350d-018a-49cf-a28e-e5ce21fe7dec@gmail.com","subject":"Re: [PATCH 4/8] SubmittingPatches: update extra tags list","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2023-12-20T15:30:01Z","receivedAt":"2023-12-20T15:30:15Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"To add to what Phillip said...\n\nOn Wed, Dec 20, 2023 at 7:18 AM Phillip Wood wrote:\n>\n> Hi Josh\n>\n> On 19/12/2023 08:41, Josh Soref via GitGitGadget wrote:\n> > From: Josh Soref \n> >\n> > Add items with at least 100 uses:\n> > - Co-authored-by\n> > - Helped-by\n> > - Mentored-by\n> > - Suggested-by\n>\n> Thanks for adding these, they are widely used and should be documented.\n> The patch also adds a mention for \"Noticed-by:\" - I'm less convinced by\n> the need for that as I explain below.\n>\n> > Updating the create suggestion to something less commonly used.\n>\n> I'm not quite sure I understand what you mean by this sentence.\n\nSame.\n\n> > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> > index 32e90238777..694a7bafb68 100644\n> > --- a/Documentation/SubmittingPatches\n> > +++ b/Documentation/SubmittingPatches\n> > @@ -348,6 +348,8 @@ If you like, you can put extra tags at the end:\n> >\n> > . `Reported-by:` is used to credit someone who found the bug that\n> > the patch attempts to fix.\n> > +. `Noticed-by:` liked `Reported-by:` indicates someone who noticed\n> > + the item being fixed.\n>\n> I wonder if we really need a separate \"Noticed-by\" footer in addition to\n> \"Reported-by\". Personally I use the latter to acknowledge the person who\n> reported the issue being fix regards of weather I'm fixing a bug or some\n> other issue.\n\nI'm not sure I'd mention both either; feels like we're making it hard\nfor users to choose. Also, I think there's a minor distinction\nbetween them, but it's hard to convey simply: To me, Reported-by\nsuggests someone sent a mail to the list specifically about the bug or\nissue in question. Also, to me, Noticed-by suggests that during a\nback-and-forth discussion of some sort on another topic, a fellow Git\ncontributor noticed an issue and mentioned it as an aside. But,\nthat's how _I_ would have used them, I didn't do any digging to find\nout if that's really how they are used.\n\nEither way, if we're going to define them as synonyms, I'd rather we\njust left the less common one out. If there's a distinction, and it's\nnot a pain to describe, then maybe it'd be worth adding both.\n\nIf we do add both, though, we at least need to fix \"liked\" to \"like\"\nin your description.\n\n> > . `Acked-by:` says that the person who is more familiar with the area\n> > the patch attempts to modify liked the patch.\n> > . `Reviewed-by:`, unlike the other tags, can only be offered by the\n> > @@ -355,9 +357,17 @@ If you like, you can put extra tags at the end:\n> > patch after a detailed analysis.\n> > . `Tested-by:` is used to indicate that the person applied the patch\n> > and found it to have the desired effect.\n> > +. `Co-authored-by:` is used to indicate that multiple people\n> > + contributed to the work of a patch.\n>\n> Junio's comments in [1] may be helpful here\n>\n> If co-authors closely worked together (possibly but not necessarily\n> outside the public view), exchanging drafts and agreeing on the\n> final version before sending it to the list, by one approving the\n> other's final draft, Co-authored-by may be appropriate.\n>\n> I would prefer to see more use of Helped-by when suggestions for\n> improvements were made, possibly but not necessarily in a concrete\n> \"squashable patch\" form, the original author accepted before\n> sending the new version out, and the party who made suggestions saw\n> the updated version at the same time as the general public.\n>\n> So I think we should be clear that \"Co-authored-by:\" means that multiple\n> authors worked closely together on the patch, rather than just\n> contributed to it.\n>\n> [1] https://lore.kernel.org/git/xmqqmth8wwcf.fsf@gitster.g/\n>\n> > +. `Helped-by:` is used to credit someone with helping develop a\n> > + patch.\n> > +. `Mentored-by:` is used to credit someone with helping develop a\n> > + patch.\n>\n> I think we use \"Montored-by:\" specifically to credit the mentor on\n> patches written by GSoC or Outreachy interns and \"Helped-by:\" for the\n> general case of someone helping the patch author.\n\nYes; I'd like for these to be distinguished in this way or something similar.\n\n> > +. `Suggested-by:` is used to credit someone with suggesting the idea\n> > + for a patch.\n> >\n> > You can also create your own tag or use one that's in common usage\n> > -such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Mentored-by:\".\n> > +such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Improved-by:\".\n>\n> What's the difference between \"Improved-by:\" and \"Helped-by:\"? In\n> general I'd prefer for us not to encourage new trailers where we already\n> have a suitable one in use.\n\nAgreed.\n\n> Thanks for working on this, it will be good to have better descriptions\n> of our common trailers.\n\nAgreed here as well; thanks for the work, Josh.\n"},{"id":"485866","messageId":"CABPp-BFU+4Xy8tVrU5qV3GX7Mr3-nOEtSgix3MSne5VVW2hz2Q@mail.gmail.com","threadId":"60631","inReplyTo":"e788cf7b-56c7-48c2-ad4f-65d9c9e73ad5@web.de","subject":"Re: [PATCH 6/8] SubmittingPatches: clarify GitHub visual","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2023-12-20T15:40:25Z","receivedAt":"2023-12-20T15:40:39Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Tue, Dec 19, 2023 at 6:44 AM René Scharfe wrote:\n>\n> Am 19.12.23 um 09:41 schrieb Josh Soref via GitGitGadget:\n> > From: Josh Soref \n> >\n> > Some people would expect a cross to be upright, and potentially have\n> > unequal lengths...\n>\n> There are lots of types of crosses. And while looking them up on\n> Wikipedia I learned today that an x-cross is called \"saltire\" in\n> English. I only knew it as St. Andrew's cross before.\n>\n> > GitHub uses a white x overlaying a solid red circle to indicate failure.\n>\n> They call it \"x-circle-fill\"\n> (https://primer.github.io/octicons/x-circle-fill-16).\n>\n> >\n> > Signed-off-by: Josh Soref \n> > ---\n> > Documentation/SubmittingPatches | 2 +-\n> > 1 file changed, 1 insertion(+), 1 deletion(-)\n> >\n> > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> > index d7a84f59478..8e19c7f82e4 100644\n> > --- a/Documentation/SubmittingPatches\n> > +++ b/Documentation/SubmittingPatches\n> > @@ -604,7 +604,7 @@ to your fork of Git on GitHub. You can monitor the test state of all your\n> > branches here: `https://github.com//git/actions/workflows/main.yml`\n> >\n> > If a branch did not pass all test cases then it is marked with a red\n> > -cross. In that case you can click on the failing job and navigate to\n> > ++x+. In that case you can click on the failing job and navigate to\n>\n> In the commit message you say the x is white, here it's red, so what is\n> it? IIUC the circle is red and the x-cross inside is the same color as\n> the background, i.e. white in light mode and black in dark mode. No\n> idea how to express that in one word. Perhaps \"red circle containing\n> and x-cross\"?\n\nThere's an \"and\" vs \"an\" typo there, I think. I'm tempted to just\noversimplify (\"...marked with red.\"), but am slightly concerned about\nred/green color-blind folks. I suspect they'd figure it out anyway by\ncomparing the checkmarks (within green) to the x's (within red), but\nif we want to be more detailed, perhaps we drop the \"cross\" altogether\nand just describe it literally: \"...marked with a red circle\ncontaining a white x.\"?\n"},{"id":"485868","messageId":"CABPp-BF8s-qiXWPMSae0pB+eRLDRO47Fj-7YRfS38SQ+6bBMzA@mail.gmail.com","threadId":"60631","inReplyTo":"pull.1623.git.1702975319.gitgitgadget@gmail.com","subject":"Re: [PATCH 0/8] Minor improvements to CodingGuidelines and SubmittingPatches","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2023-12-20T15:43:35Z","receivedAt":"2023-12-20T15:43:48Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Tue, Dec 19, 2023 at 12:42 AM Josh Soref via GitGitGadget\n wrote:\n>\n> These are a bunch of things I've run into over my past couple of attempts to\n> contribute to Git.\n>\n> * Incremental punctuation/grammatical improvements\n> * Update extra tags suggestions based on common usage\n> * drop reference to an article that was discontinued over a decade ago\n> * update GitHub references\n> * harmonize non-ASCII while I'm here\n\nI commented on patches 4, 6, and 7 suggesting some changes. Patch 1\nis \"meh\" to me, but it doesn't hurt anything. The other four all look\nlike good cleanups to me.\n"},{"id":"485870","messageId":"CACZqfqAiSpGP5ABN7MZ50Za=-vAEKnqE0ravzEMbLJCByfRd8w@mail.gmail.com","threadId":"60631","inReplyTo":"CABPp-BH_iP2KjPi-5kW8ROQWfy8XoUmbGhyT-Y1dZGtCtZXQGQ@mail.gmail.com","subject":"Re: [PATCH 4/8] SubmittingPatches: update extra tags list","fromName":"Josh Soref","fromEmail":"jsoref@gmail.com","sentAt":"2023-12-20T16:09:12Z","receivedAt":"2023-12-20T16:09:27Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"On Wed, Dec 20, 2023 at 10:30 AM Elijah Newren wrote:\n> On Wed, Dec 20, 2023 at 7:18 AM Phillip Wood wrote:\n> > Thanks for adding these, they are widely used and should be documented.\n> > The patch also adds a mention for \"Noticed-by:\" - I'm less convinced by\n> > the need for that as I explain below.\n> >\n> > > Updating the create suggestion to something less commonly used.\n> >\n> > I'm not quite sure I understand what you mean by this sentence.\n\nTentatively rewritten as:\n Updating the \"create your own tag\" suggestion as 'Mentored-by' has been\n promoted.\n\nThis commit is adding bulleted items including promoting 'Mentored-by',\nwhich means that the suggestion of \"invent your own\" would really need\na new suggestion.\n\nPersonally I'm not a fan of \"invent your own\", but I'm trying to\nfollow \"when in Rome\" (which is a big thing in the Git process\ndocumentation covered by the two files subject to this series). More\non this later.\n\n> > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> > > index 32e90238777..694a7bafb68 100644\n> > > @@ -348,6 +348,8 @@ If you like, you can put extra tags at the end:\n> > >\n> > > . `Reported-by:` is used to credit someone who found the bug that\n> > > the patch attempts to fix.\n> > > +. `Noticed-by:` liked `Reported-by:` indicates someone who noticed\n> > > + the item being fixed.\n> >\n> > I wonder if we really need a separate \"Noticed-by\" footer in addition to\n> > \"Reported-by\". Personally I use the latter to acknowledge the person who\n> > reported the issue being fix regards of weather I'm fixing a bug or some\n> > other issue.\n>\n> I'm not sure I'd mention both either; feels like we're making it hard\n> for users to choose. Also, I think there's a minor distinction\n> between them, but it's hard to convey simply: To me, Reported-by\n> suggests someone sent a mail to the list specifically about the bug or\n> issue in question. Also, to me, Noticed-by suggests that during a\n> back-and-forth discussion of some sort on another topic, a fellow Git\n> contributor noticed an issue and mentioned it as an aside. But,\n> that's how _I_ would have used them, I didn't do any digging to find\n> out if that's really how they are used.\n\nGiven that Noticed-by is more common than Co-authored-by, I have a\nhard time arguing that it shouldn't be included.\nYou could see that I struggled with it based on my lousy first drafts [1].\n\nAnyway, tentatively:\n\n. `Noticed-by:` like `Reported-by:` indicates a Git contributor who\ncalled the item (being fixed) out as an aside.\n\nHere, I'm struggling with the tension between \"noticed-by probably\nhints that something is being fixed\" and \"noticed-by is addressing who\nsuggested it and why we're attributing it to them\"\n\n\"as an aside\" is itself an ellipsis for something like \"as an aside to\nsome unrelated discussion and didn't really circle back to it as a top\nlevel discussion point, but here we're closing the loop\" -- but this\nis obviously way too long-winded to be the written form.\n\n> Either way, if we're going to define them as synonyms, I'd rather we\n> just left the less common one out. If there's a distinction, and it's\n> not a pain to describe, then maybe it'd be worth adding both.\n>\n> If we do add both, though, we at least need to fix \"liked\" to \"like\"\n> in your description.\n\nRight, it's a \"first draft\" [1]...\n\n> > > +. `Co-authored-by:` is used to indicate that multiple people\n> > > + contributed to the work of a patch.\n> >\n> > Junio's comments in [1] may be helpful here\n> >\n> > If co-authors closely worked together (possibly but not necessarily\n> > outside the public view), exchanging drafts and agreeing on the\n> > final version before sending it to the list, by one approving the\n> > other's final draft, Co-authored-by may be appropriate.\n> >\n> > I would prefer to see more use of Helped-by when suggestions for\n> > improvements were made, possibly but not necessarily in a concrete\n> > \"squashable patch\" form, the original author accepted before\n> > sending the new version out, and the party who made suggestions saw\n> > the updated version at the same time as the general public.\n> >\n> > So I think we should be clear that \"Co-authored-by:\" means that multiple\n> > authors worked closely together on the patch, rather than just\n> > contributed to it.\n\nTentatively:\n. `Co-authored-by:` is used to indicate that people exchanged drafts\nof a patch before submitting it.\n\nNote that I'm dropping `multiple` -- people implies that.\n\n. `Helped-by:` is used to credit someone who suggested ideas for\nchanges without providing the precise changes in patch form.\n\n> > I think we use \"Montored-by:\" specifically to credit the mentor on\n> > patches written by GSoC or Outreachy interns and \"Helped-by:\" for the\n> > general case of someone helping the patch author.\n>\n> Yes; I'd like for these to be distinguished in this way or something similar.\n\n. `Mentored-by:` is used to credit someone with helping develop a\npatch as part of a mentorship program (e.g., GSoC or Outreachy).\n\n> > > You can also create your own tag or use one that's in common usage\n> > > -such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Mentored-by:\".\n> > > +such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Improved-by:\".\n> >\n> > What's the difference between \"Improved-by:\" and \"Helped-by:\"?\n\nI dunno. This entire section (as I called out at the beginning) is\nfrustrating...\n\nAnyway, see all of us struggle with it below:\n\n> > In\n> > general I'd prefer for us not to encourage new trailers where we already\n> > have a suitable one in use.\n\nIf this text needs to survive without being drastically changed, it\nneeds a warning saying \"don't create a new tag if there's an already\nused tag that seems like it'll cover what you're trying to say --\nhere's how to review them...\". Note that I'd argue the cost being\nasked of someone to do this research far exceeds what is reasonable to\nask of a new contributor, which is why I'd rather say that new\ncontributors shouldn't be inventing tags.\n\n> Agreed.\n\nI personally agree. I think encouraging non-core contributors to\ninvent their own is not a good idea. It leads to various things\n(including inconsistently cased items because users fail to review the\ncurrent set / understand them/their-construction).\n\nSaying that it's ok for core contributors to suggest a new tag and\nthat if a core contributor suggests a new tag that the person writing\nthe current series should just accept the tag and trust that it'll be\nok.\n\nNote: I'm not going to draft wording to this effect on my own, and if\nI were to provide such a change, it'd be its own commit prior to the\none here, because it's a significant process change as opposed to\nclarifying the list of recommended tags.\n\n> > Thanks for working on this, it will be good to have better descriptions\n> > of our common trailers.\n>\n> Agreed here as well; thanks for the work, Josh.\n\n[1] The Late Show With Stephen Colbert has a running segment called\nFirst Drafts which showcases lousy first drafts of greeting cards,\nthey've https://www.cbsstore.com/products/the-late-show-with-stephen-colbert-first-drafts-greeting-card-pack-sc1193\n"},{"id":"485871","messageId":"CACZqfqDVBHyBCgUwAJDv838cvF4xTo_UobA-_s6hqTzTG1c9qg@mail.gmail.com","threadId":"60631","inReplyTo":"CABPp-BFbLN7dsKvm+___y6s8OWARhXB5BHq5N3sKWaf66RPzDg@mail.gmail.com","subject":"Re: [PATCH 7/8] SubmittingPatches: clarify GitHub artifact format","fromName":"Josh Soref","fromEmail":"jsoref@gmail.com","sentAt":"2023-12-20T16:16:08Z","receivedAt":"2023-12-20T16:16:22Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"Elijah Newren wrote:\n> > From: Josh Soref \n> >\n> > GitHub wraps artifacts generated by workflows in a .zip file.\n> >\n> > Internally workflows can package anything they like in them.\n>\n> s/Internally/Internal/?\n\nNo, it's actually:\n\ns/Internally/Internally,/\n\nIn that, what a workflow does to structure the contents of a .zip\nartifact is an implementation decision of the workflow.\n"},{"id":"485872","messageId":"CACZqfqCM88M+saToOYVC7iXqFZdrivuq=KGLmh-Scx3H0ZSWrw@mail.gmail.com","threadId":"60631","inReplyTo":"CABPp-BFU+4Xy8tVrU5qV3GX7Mr3-nOEtSgix3MSne5VVW2hz2Q@mail.gmail.com","subject":"Re: [PATCH 6/8] SubmittingPatches: clarify GitHub visual","fromName":"Josh Soref","fromEmail":"jsoref@gmail.com","sentAt":"2023-12-20T16:25:08Z","receivedAt":"2023-12-20T16:25:22Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"Elijah Newren wrote:\n> On Tue, Dec 19, 2023 at 6:44 AM René Scharfe wrote:\n> > Am 19.12.23 um 09:41 schrieb Josh Soref via GitGitGadget:\n> > > From: Josh Soref \n> > > Some people would expect a cross to be upright, and potentially have\n> > > unequal lengths...\n> > There are lots of types of crosses. And while looking them up on\n> > Wikipedia I learned today that an x-cross is called \"saltire\" in\n> > English. I only knew it as St. Andrew's cross before.\n> >\n> > > GitHub uses a white x overlaying a solid red circle to indicate failure.\n> >\n> > They call it \"x-circle-fill\"\n> > (https://primer.github.io/octicons/x-circle-fill-16).\n\n> > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> > > @@ -604,7 +604,7 @@ to your fork of Git on GitHub. You can monitor the test state of all your\n> > > branches here: `https://github.com//git/actions/workflows/main.yml`\n> > >\n> > > If a branch did not pass all test cases then it is marked with a red\n> > > -cross. In that case you can click on the failing job and navigate to\n> > > ++x+. In that case you can click on the failing job and navigate to\n> >\n> > In the commit message you say the x is white, here it's red, so what is\n> > it? IIUC the circle is red and the x-cross inside is the same color as\n> > the background, i.e. white in light mode and black in dark mode. No\n> > idea how to express that in one word. Perhaps \"red circle containing\n> > and x-cross\"?\n\nThis was an oversimplification, which I deeply regret.\n\nIt uses a simple red x (❌) in some views, e.g.:\nhttps://github.com/gitgitgadget/git/pull/1620\n\nAnd in other views it uses a red circle with what's actually a\ntransparent x (white at the top if using light mode, gray fill if you\nselect linux-leaks on the left, and dark gray fill in the log view):\nhttps://github.com/gitgitgadget/git/actions/runs/7265353611/job/19794849212?pr=1620\n\n> There's an \"and\" vs \"an\" typo there, I think. I'm tempted to just\n> oversimplify (\"...marked with red.\"), but am slightly concerned about\n> red/green color-blind folks. I suspect they'd figure it out anyway by\n> comparing the checkmarks (within green) to the x's (within red), but\n> if we want to be more detailed, perhaps we drop the \"cross\" altogether\n> and just describe it literally: \"...marked with a red circle\n> containing a white x.\"?\n\nYour text aligns with what I drafted as a response but didn't send:\n\nI think it's simplest to say an `x`, or maybe \"red color and an x\".\n"},{"id":"485874","messageId":"xmqqh6kcu96z.fsf@gitster.g","threadId":"60631","inReplyTo":"35fc350d-018a-49cf-a28e-e5ce21fe7dec@gmail.com","subject":"Re: [PATCH 4/8] SubmittingPatches: update extra tags list","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-20T16:31:48Z","receivedAt":"2023-12-20T16:32:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Phillip Wood writes:\n\n> What's the difference between \"Improved-by:\" and \"Helped-by:\"? In\n> general I'd prefer for us not to encourage new trailers where we\n> already have a suitable one in use.\n\nI agree with the direction to limit the trailer tokens to common\nones, as the repertoire we have sufficiently covers the needs\nalready, and strongly discourage folks to waste their time trying to\nbe \"original\".\n\nIt might be useful to run stats of trailers that were used in the\npast, say, 3 years and that may give us a good guide to decide which\nones to limit ourselves to.\n\nThanks for reviewing.\n\n"},{"id":"485875","messageId":"xmqq8r5ou8u9.fsf@gitster.g","threadId":"60631","inReplyTo":"CABPp-BFU+4Xy8tVrU5qV3GX7Mr3-nOEtSgix3MSne5VVW2hz2Q@mail.gmail.com","subject":"Re: [PATCH 6/8] SubmittingPatches: clarify GitHub visual","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-20T16:39:26Z","receivedAt":"2023-12-20T16:39:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Elijah Newren writes:\n\n> ... I'm tempted to just\n> oversimplify (\"...marked with red.\"), but am slightly concerned about\n> red/green color-blind folks.\n\n(sheepishly raises hand). Thanks for being considerate.\n\n> I suspect they'd figure it out anyway by\n> comparing the checkmarks (within green) to the x's (within red),\n\nI 100% agree with this.\n\n> but\n> if we want to be more detailed, perhaps we drop the \"cross\" altogether\n> and just describe it literally: \"...marked with a red circle\n> containing a white x.\"?\n\nThanks.\n"},{"id":"485876","messageId":"CABPp-BFjotLN4sCe+6uHAU7qhr1COM0B4EdW0f0-X-xf5qXinA@mail.gmail.com","threadId":"60631","inReplyTo":"CACZqfqAiSpGP5ABN7MZ50Za=-vAEKnqE0ravzEMbLJCByfRd8w@mail.gmail.com","subject":"Re: [PATCH 4/8] SubmittingPatches: update extra tags list","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2023-12-20T16:49:48Z","receivedAt":"2023-12-20T16:50:02Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Wed, Dec 20, 2023 at 8:09 AM Josh Soref wrote:\n>\n> On Wed, Dec 20, 2023 at 10:30 AM Elijah Newren wrote:\n> > On Wed, Dec 20, 2023 at 7:18 AM Phillip Wood wrote:\n> > > Thanks for adding these, they are widely used and should be documented.\n> > > The patch also adds a mention for \"Noticed-by:\" - I'm less convinced by\n> > > the need for that as I explain below.\n> > >\n> > > > Updating the create suggestion to something less commonly used.\n> > >\n> > > I'm not quite sure I understand what you mean by this sentence.\n>\n> Tentatively rewritten as:\n> Updating the \"create your own tag\" suggestion as 'Mentored-by' has been\n> promoted.\n>\n> This commit is adding bulleted items including promoting 'Mentored-by',\n> which means that the suggestion of \"invent your own\" would really need\n> a new suggestion.\n>\n> Personally I'm not a fan of \"invent your own\", but I'm trying to\n> follow \"when in Rome\" (which is a big thing in the Git process\n> documentation covered by the two files subject to this series). More\n> on this later.\n\nYeah, well it appears that those of us who have been here in Rome for\na while aren't a fan of it anymore either; see also Junio's response\nin this thread about that.\n\n> > > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> > > > index 32e90238777..694a7bafb68 100644\n> > > > @@ -348,6 +348,8 @@ If you like, you can put extra tags at the end:\n> > > >\n> > > > . `Reported-by:` is used to credit someone who found the bug that\n> > > > the patch attempts to fix.\n> > > > +. `Noticed-by:` liked `Reported-by:` indicates someone who noticed\n> > > > + the item being fixed.\n> > >\n> > > I wonder if we really need a separate \"Noticed-by\" footer in addition to\n> > > \"Reported-by\". Personally I use the latter to acknowledge the person who\n> > > reported the issue being fix regards of weather I'm fixing a bug or some\n> > > other issue.\n> >\n> > I'm not sure I'd mention both either; feels like we're making it hard\n> > for users to choose. Also, I think there's a minor distinction\n> > between them, but it's hard to convey simply: To me, Reported-by\n> > suggests someone sent a mail to the list specifically about the bug or\n> > issue in question. Also, to me, Noticed-by suggests that during a\n> > back-and-forth discussion of some sort on another topic, a fellow Git\n> > contributor noticed an issue and mentioned it as an aside. But,\n> > that's how _I_ would have used them, I didn't do any digging to find\n> > out if that's really how they are used.\n>\n> Given that Noticed-by is more common than Co-authored-by, I have a\n> hard time arguing that it shouldn't be included.\n\nNot if you look at the last three years; there Co-authored-by is more\nthan 17 times more common than Noticed-by.\n\n> You could see that I struggled with it based on my lousy first drafts [1].\n>\n> Anyway, tentatively:\n>\n> . `Noticed-by:` like `Reported-by:` indicates a Git contributor who\n> called the item (being fixed) out as an aside.\n>\n> Here, I'm struggling with the tension between \"noticed-by probably\n> hints that something is being fixed\" and \"noticed-by is addressing who\n> suggested it and why we're attributing it to them\"\n>\n> \"as an aside\" is itself an ellipsis for something like \"as an aside to\n> some unrelated discussion and didn't really circle back to it as a top\n> level discussion point, but here we're closing the loop\" -- but this\n> is obviously way too long-winded to be the written form\n\nGiven the large drop-off in usage of the Noticed-by trailer, I'd\nsuggest just leaving it out.\n\n> > Either way, if we're going to define them as synonyms, I'd rather we\n> > just left the less common one out. If there's a distinction, and it's\n> > not a pain to describe, then maybe it'd be worth adding both.\n> >\n> > If we do add both, though, we at least need to fix \"liked\" to \"like\"\n> > in your description.\n>\n> Right, it's a \"first draft\" [1]...\n\n:-)\n\n[...]\n\n> I personally agree. I think encouraging non-core contributors to\n> invent their own is not a good idea. It leads to various things\n> (including inconsistently cased items because users fail to review the\n> current set / understand them/their-construction).\n>\n> Saying that it's ok for core contributors to suggest a new tag and\n> that if a core contributor suggests a new tag that the person writing\n> the current series should just accept the tag and trust that it'll be\n> ok.\n>\n> Note: I'm not going to draft wording to this effect on my own, and if\n> I were to provide such a change, it'd be its own commit prior to the\n> one here, because it's a significant process change as opposed to\n> clarifying the list of recommended tags.\n\nPerhaps replace\n\n You can also create your own tag or use one that's in common usage\n such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Mentored-by:\".\n\nwith\n\n While you can also create your own trailer if the situation warrants it, we\n encourage you to instead use one of the common trailers in this project\n highlighted above.\n\n?\n"},{"id":"485878","messageId":"CABPp-BH+f_+hwTPF8-pivDKtFmzEyiw2NW1R9jiF24Koo1CEVw@mail.gmail.com","threadId":"60631","inReplyTo":"CACZqfqDVBHyBCgUwAJDv838cvF4xTo_UobA-_s6hqTzTG1c9qg@mail.gmail.com","subject":"Re: [PATCH 7/8] SubmittingPatches: clarify GitHub artifact format","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2023-12-20T17:00:21Z","receivedAt":"2023-12-20T17:00:34Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Wed, Dec 20, 2023 at 8:16 AM Josh Soref wrote:\n>\n> Elijah Newren wrote:\n> > > From: Josh Soref \n> > >\n> > > GitHub wraps artifacts generated by workflows in a .zip file.\n> > >\n> > > Internally workflows can package anything they like in them.\n> >\n> > s/Internally/Internal/?\n>\n> No, it's actually:\n>\n> s/Internally/Internally,/\n>\n> In that, what a workflow does to structure the contents of a .zip\n> artifact is an implementation decision of the workflow.\n\nAh, that makes sense with the comma; thanks.\n"},{"id":"485880","messageId":"CACZqfqCar=tay5diocU7jVWBwPUFqewNYfPLHkYvvR1fSBSdPA@mail.gmail.com","threadId":"60631","inReplyTo":"CABPp-BFjotLN4sCe+6uHAU7qhr1COM0B4EdW0f0-X-xf5qXinA@mail.gmail.com","subject":"Re: [PATCH 4/8] SubmittingPatches: update extra tags list","fromName":"Josh Soref","fromEmail":"jsoref@gmail.com","sentAt":"2023-12-20T17:42:44Z","receivedAt":"2023-12-20T17:42:58Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"Elijah Newren wrote:\n> Yeah, well it appears that those of us who have been here in Rome for\n> a while aren't a fan of it anymore either; see also Junio's response\n> in this thread about that.\n\nRight.\n\n> [Josh Soref wrote:]\n> > Given that Noticed-by is more common than Co-authored-by, I have a\n> > hard time arguing that it shouldn't be included.\n>\n> Not if you look at the last three years; there Co-authored-by is more\n> than 17 times more common than Noticed-by.\n\n> Given the large drop-off in usage of the Noticed-by trailer, I'd\n> suggest just leaving it out.\n\n\n\n> Perhaps replace\n>\n> You can also create your own tag or use one that's in common usage\n> such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Mentored-by:\".\n>\n> with\n>\n> While you can also create your own trailer if the situation warrants it, we\n> encourage you to instead use one of the common trailers in this project\n> highlighted above.\n>\n> ?\n\nLet's have some fun (inception):\n\ncommit eac2211332f754c5f4127a58aafb9882bfe939e8\nAuthor: Josh Soref \nDate: Wed Dec 20 12:34:54 2023 -0500\n\n SubmittingPatches: discourage new trailers\n\n There seems to be consensus amongst the core Git community on a working\n set of common trailers, and there are non-trivial costs to people\n inventing new trailers (research to discover what they mean/how they\n differ from existing trailers) such that inventing new ones is generally\n unwarranted and not something to be recommended to new contributors.\n\n Suggested-by: Elijah Newren \n Signed-off-by: Josh Soref \n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 32e9023877..58dfe40504 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -358,4 +358,5 @@ If you like, you can put extra tags at the end:\n\n-You can also create your own tag or use one that's in common usage\n-such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Mentored-by:\".\n+While you can also create your own trailer if the situation warrants it, we\n+encourage you to instead use one of the common trailers in this project\n+highlighted above.\n"},{"id":"485931","messageId":"e4b6eda6-8d20-48b3-a33d-13ee07d227ce@gmail.com","threadId":"60631","inReplyTo":"CACZqfqCar=tay5diocU7jVWBwPUFqewNYfPLHkYvvR1fSBSdPA@mail.gmail.com","subject":"Re: [PATCH 4/8] SubmittingPatches: update extra tags list","fromName":"","fromEmail":"phillip.wood123@gmail.com","sentAt":"2023-12-21T15:09:59Z","receivedAt":"2023-12-21T15:10:01Z","isPatch":true,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"Hi Josh\n\nOn 20/12/2023 17:42, Josh Soref wrote:\n> SubmittingPatches: discourage new trailers\n> \n> There seems to be consensus amongst the core Git community on a working\n> set of common trailers, and there are non-trivial costs to people\n> inventing new trailers (research to discover what they mean/how they\n> differ from existing trailers) such that inventing new ones is generally\n> unwarranted and not something to be recommended to new contributors.\n> \n> Suggested-by: Elijah Newren \n> Signed-off-by: Josh Soref \n> \n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> index 32e9023877..58dfe40504 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -358,4 +358,5 @@ If you like, you can put extra tags at the end:\n> \n> -You can also create your own tag or use one that's in common usage\n> -such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Mentored-by:\".\n> +While you can also create your own trailer if the situation warrants it, we\n> +encourage you to instead use one of the common trailers in this project\n> +highlighted above.\n\nThanks for this, it looks good and would be a useful addition to v2 of \nyour patch series.\n\nBest Wishes\n\nPhillip\n\n"},{"id":"485933","messageId":"pull.1623.v2.git.1703176865.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.git.1702975319.gitgitgadget@gmail.com","subject":"[PATCH v2 0/9] Minor improvements to CodingGuidelines and SubmittingPatches","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-21T16:40:56Z","receivedAt":"2023-12-21T16:41:08Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"These are a bunch of things I've run into over my past couple of attempts to\ncontribute to Git.\n\n * Incremental punctuation/grammatical improvements\n * Update extra tags suggestions based on common usage\n * drop reference to an article that was discontinued over a decade ago\n * update GitHub references\n * harmonize non-ASCII while I'm here\n\nNote that I'm trying to do things \"in the neighborhood\". It'll be slower\nthan me replacing things topically, but hopefully easier for others to\ndigest. My current estimate is a decade or two :).\n\nJosh Soref (9):\n CodingGuidelines: move period inside parentheses\n CodingGuidelines: write punctuation marks\n SubmittingPatches: drop ref to \"What's in git.git\"\n SubmittingPatches: discourage new trailers\n SubmittingPatches: update extra tags list\n SubmittingPatches: improve extra tags advice\n SubmittingPatches: clarify GitHub visual\n SubmittingPatches: clarify GitHub artifact format\n SubmittingPatches: hyphenate non-ASCII\n\n Documentation/CodingGuidelines | 4 ++--\n Documentation/SubmittingPatches | 27 ++++++++++++++++++++-------\n 2 files changed, 22 insertions(+), 9 deletions(-)\n\n\nbase-commit: 624eb90fa8f65a79396615f3c2842ac5a3743350\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1623%2Fjsoref%2Fdocumentation-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1623/jsoref/documentation-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/1623\n\nRange-diff vs v1:\n\n 1: b9a8eb6aa4e = 1: b9a8eb6aa4e CodingGuidelines: move period inside parentheses\n 2: c0db8336e51 = 2: c0db8336e51 CodingGuidelines: write punctuation marks\n 3: 22d66c5b78a = 3: 22d66c5b78a SubmittingPatches: drop ref to \"What's in git.git\"\n 4: e5c7f29af43 ! 4: eac2211332f SubmittingPatches: update extra tags list\n @@ Metadata\n Author: Josh Soref \n \n ## Commit message ##\n - SubmittingPatches: update extra tags list\n + SubmittingPatches: discourage new trailers\n \n - Add items with at least 100 uses:\n - - Co-authored-by\n - - Helped-by\n - - Mentored-by\n - - Suggested-by\n -\n - Updating the create suggestion to something less commonly used.\n -\n - git log |\n - perl -ne 'next unless /^\\s+[A-Z][a-z]+-\\S+:/;s/^\\s+//;s/:.*/:/;print'|\n - sort|uniq -c|sort -n|grep '[0-9][0-9] '\n - 11 Helped-By:\n - 13 Message-ID:\n - 14 Reported-By:\n - 22 Acked-By:\n - 27 Inspired-by:\n - 29 Requested-by:\n - 35 Original-patch-by:\n - 43 Contributions-by:\n - 47 Signed-Off-By:\n - 65 Based-on-patch-by:\n - 68 Thanks-to:\n - 88 Improved-by:\n - 145 Co-authored-by:\n - 171 Noticed-by:\n - 182 Tested-by:\n - 361 Suggested-by:\n - 469 Mentored-by:\n - 1196 Reported-by:\n - 1727 Helped-by:\n - 2177 Reviewed-by:\n - 2202 Acked-by:\n - 95313 Signed-off-by:\n + There seems to be consensus amongst the core Git community on a working\n + set of common trailers, and there are non-trivial costs to people\n + inventing new trailers (research to discover what they mean/how they\n + differ from existing trailers) such that inventing new ones is generally\n + unwarranted and not something to be recommended to new contributors.\n \n + Suggested-by: Elijah Newren \n Signed-off-by: Josh Soref \n \n ## Documentation/SubmittingPatches ##\n @@ Documentation/SubmittingPatches: If you like, you can put extra tags at the end:\n - \n - . `Reported-by:` is used to credit someone who found the bug that\n - the patch attempts to fix.\n -+. `Noticed-by:` liked `Reported-by:` indicates someone who noticed\n -+ the item being fixed.\n - . `Acked-by:` says that the person who is more familiar with the area\n - the patch attempts to modify liked the patch.\n - . `Reviewed-by:`, unlike the other tags, can only be offered by the\n -@@ Documentation/SubmittingPatches: If you like, you can put extra tags at the end:\n - patch after a detailed analysis.\n . `Tested-by:` is used to indicate that the person applied the patch\n and found it to have the desired effect.\n -+. `Co-authored-by:` is used to indicate that multiple people\n -+ contributed to the work of a patch.\n -+. `Helped-by:` is used to credit someone with helping develop a\n -+ patch.\n -+. `Mentored-by:` is used to credit someone with helping develop a\n -+ patch.\n -+. `Suggested-by:` is used to credit someone with suggesting the idea\n -+ for a patch.\n \n - You can also create your own tag or use one that's in common usage\n +-You can also create your own tag or use one that's in common usage\n -such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Mentored-by:\".\n -+such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Improved-by:\".\n ++While you can also create your own trailer if the situation warrants it, we\n ++encourage you to instead use one of the common trailers in this project\n ++highlighted above.\n \n [[git-tools]]\n === Generate your patch using Git tools out of your commits.\n -: ----------- > 5: 8848572fe2c SubmittingPatches: update extra tags list\n 5: 11688e4360c ! 6: 8f16c7caa73 SubmittingPatches: improve extra tags advice\n @@ Commit message\n Signed-off-by: Josh Soref \n \n ## Documentation/SubmittingPatches ##\n -@@ Documentation/SubmittingPatches: If you like, you can put extra tags at the end:\n - You can also create your own tag or use one that's in common usage\n - such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Improved-by:\".\n +@@ Documentation/SubmittingPatches: While you can also create your own trailer if the situation warrants it, we\n + encourage you to instead use one of the common trailers in this project\n + highlighted above.\n \n +Extra tags should only capitalize the very first letter, i.e. favor\n +\"Signed-off-by\" over \"Signed-Off-By\" and \"Acked-by:\" over \"Acked-By\".\n 6: 043d2a24202 ! 7: cdb5fd0957f SubmittingPatches: clarify GitHub visual\n @@ Metadata\n ## Commit message ##\n SubmittingPatches: clarify GitHub visual\n \n - Some people would expect a cross to be upright, and potentially have\n - unequal lengths...\n + GitHub has two general forms for its states, sometimes they're a simple\n + colored object (e.g. green check or red x), and sometimes there's also a\n + colored container (e.g. green box or red circle) with containing that\n + object (e.g. check or x).\n \n - GitHub uses a white x overlaying a solid red circle to indicate failure.\n + That's a lot of words to try to describe things, but in general, the key\n + for a failure is that it's recognized as an `x` and that it's associated\n + with the color red -- the color of course is problematic for people who\n + are red-green color-blind, but that's why they are paired with distinct\n + shapes.\n +\n + Using the term `cross` doesn't really help.\n \n Signed-off-by: Josh Soref \n \n 7: cdab65a4259 ! 8: 77576327df8 SubmittingPatches: clarify GitHub artifact format\n @@ Commit message\n \n GitHub wraps artifacts generated by workflows in a .zip file.\n \n - Internally workflows can package anything they like in them.\n + Internally, workflows can package anything they like in them.\n \n A recently generated failure artifact had the form:\n \n 8: 92469324813 = 9: a4878f58fe4 SubmittingPatches: hyphenate non-ASCII\n\n-- \ngitgitgadget\n"},{"id":"485934","messageId":"b9a8eb6aa4e87cd96fbf2b5d514350508076d756.1703176866.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v2.git.1703176865.gitgitgadget@gmail.com","subject":"[PATCH v2 1/9] CodingGuidelines: move period inside parentheses","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-21T16:40:57Z","receivedAt":"2023-12-21T16:41:09Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nThe contents within parenthesis should be omittable without resulting\nin broken text.\n\nEliding the parenthesis left a period to end a run without any content.\n\nSigned-off-by: Josh Soref \n---\n Documentation/CodingGuidelines | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 8ed517a5ca0..af94ed3a75d 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -450,7 +450,7 @@ For C programs:\n one of the approved headers that includes it first for you. (The\n approved headers currently include \"builtin.h\",\n \"t/helper/test-tool.h\", \"xdiff/xinclude.h\", or\n- \"reftable/system.h\"). You do not have to include more than one of\n+ \"reftable/system.h\".) You do not have to include more than one of\n these.\n \n - A C file must directly include the header files that declare the\n-- \ngitgitgadget\n\n"},{"id":"485935","messageId":"c0db8336e519cb43767effbe842dc8b97f914a4b.1703176866.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v2.git.1703176865.gitgitgadget@gmail.com","subject":"[PATCH v2 2/9] CodingGuidelines: write punctuation marks","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-21T16:40:58Z","receivedAt":"2023-12-21T16:41:10Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\n- Match style in Release Notes\n\nSigned-off-by: Josh Soref \n---\n Documentation/CodingGuidelines | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex af94ed3a75d..578587a4715 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -578,7 +578,7 @@ Externally Visible Names\n . The variable name describes the effect of tweaking this knob.\n \n The section and variable names that consist of multiple words are\n- formed by concatenating the words without punctuations (e.g. `-`),\n+ formed by concatenating the words without punctuation marks (e.g. `-`),\n and are broken using bumpyCaps in documentation as a hint to the\n reader.\n \n-- \ngitgitgadget\n\n"},{"id":"485936","messageId":"22d66c5b78a6930e195141df848266cac099ca08.1703176866.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v2.git.1703176865.gitgitgadget@gmail.com","subject":"[PATCH v2 3/9] SubmittingPatches: drop ref to \"What's in git.git\"","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-21T16:40:59Z","receivedAt":"2023-12-21T16:41:11Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\n\"What's in git.git\" was last seen in 2010:\n https://lore.kernel.org/git/?q=%22what%27s+in+git.git%22\n https://lore.kernel.org/git/7vaavikg72.fsf@alter.siamese.dyndns.org/\n\nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex bce7f97815c..32e90238777 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -570,7 +570,7 @@ their trees themselves.\n master).\n \n * Read the Git mailing list, the maintainer regularly posts messages\n- entitled \"What's cooking in git.git\" and \"What's in git.git\" giving\n+ entitled \"What's cooking in git.git\" giving\n the status of various proposed changes.\n \n == GitHub CI[[GHCI]]\n-- \ngitgitgadget\n\n"},{"id":"485937","messageId":"eac2211332f754c5f4127a58aafb9882bfe939e8.1703176866.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v2.git.1703176865.gitgitgadget@gmail.com","subject":"[PATCH v2 4/9] SubmittingPatches: discourage new trailers","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-21T16:41:00Z","receivedAt":"2023-12-21T16:41:12Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nThere seems to be consensus amongst the core Git community on a working\nset of common trailers, and there are non-trivial costs to people\ninventing new trailers (research to discover what they mean/how they\ndiffer from existing trailers) such that inventing new ones is generally\nunwarranted and not something to be recommended to new contributors.\n\nSuggested-by: Elijah Newren \nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 32e90238777..58dfe405049 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -356,8 +356,9 @@ If you like, you can put extra tags at the end:\n . `Tested-by:` is used to indicate that the person applied the patch\n and found it to have the desired effect.\n \n-You can also create your own tag or use one that's in common usage\n-such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Mentored-by:\".\n+While you can also create your own trailer if the situation warrants it, we\n+encourage you to instead use one of the common trailers in this project\n+highlighted above.\n \n [[git-tools]]\n === Generate your patch using Git tools out of your commits.\n-- \ngitgitgadget\n\n"},{"id":"485938","messageId":"8848572fe2c7432ede85e042bc2558fd8b3e8b1d.1703176866.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v2.git.1703176865.gitgitgadget@gmail.com","subject":"[PATCH v2 5/9] SubmittingPatches: update extra tags list","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-21T16:41:01Z","receivedAt":"2023-12-21T16:41:13Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nAdd items with at least 100 uses in the past three years:\n- Co-authored-by\n- Helped-by\n- Mentored-by\n- Suggested-by\n\ngit log --since=3.years|\n perl -ne 'next unless /^\\s+[A-Z][a-z]+-\\S+:/;s/^\\s+//;s/:.*/:/;print'|\n sort|uniq -c|sort -n|grep '[0-9][0-9] '\n 14 Based-on-patch-by:\n 14 Original-patch-by:\n 17 Tested-by:\n 100 Suggested-by:\n 121 Co-authored-by:\n 163 Mentored-by:\n 274 Reported-by:\n 290 Acked-by:\n 450 Helped-by:\n 602 Reviewed-by:\n14111 Signed-off-by:\n\nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 58dfe405049..31878cb70b7 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -355,6 +355,14 @@ If you like, you can put extra tags at the end:\n patch after a detailed analysis.\n . `Tested-by:` is used to indicate that the person applied the patch\n and found it to have the desired effect.\n+. `Co-authored-by:` is used to indicate that people exchanged drafts\n+ of a patch before submitting it.\n+. `Helped-by:` is used to credit someone who suggested ideas for\n+ changes without providing the precise changes in patch form.\n+. `Mentored-by:` is used to credit someone with helping develop a\n+ patch as part of a mentorship program (e.g., GSoC or Outreachy).\n+. `Suggested-by:` is used to credit someone with suggesting the idea\n+ for a patch.\n \n While you can also create your own trailer if the situation warrants it, we\n encourage you to instead use one of the common trailers in this project\n-- \ngitgitgadget\n\n"},{"id":"485939","messageId":"8f16c7caa7366cab22ad332c402f80823add8224.1703176866.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v2.git.1703176865.gitgitgadget@gmail.com","subject":"[PATCH v2 6/9] SubmittingPatches: improve extra tags advice","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-21T16:41:02Z","receivedAt":"2023-12-21T16:41:13Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nCurrent statistics show a strong preference to only capitalize the first\nletter in a hyphenated tag, but that some guidance would be helpful:\n\ngit log |\n perl -ne 'next unless /^\\s+(?:Signed-[oO]ff|Acked)-[bB]y:/;\n s/^\\s+//;s/:.*/:/;print'|\n sort|uniq -c|sort -n\n 2 Signed-off-By:\n 4 Signed-Off-by:\n 22 Acked-By:\n 47 Signed-Off-By:\n2202 Acked-by:\n95315 Signed-off-by:\n\nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 31878cb70b7..4476b52a50f 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -368,6 +368,9 @@ While you can also create your own trailer if the situation warrants it, we\n encourage you to instead use one of the common trailers in this project\n highlighted above.\n \n+Extra tags should only capitalize the very first letter, i.e. favor\n+\"Signed-off-by\" over \"Signed-Off-By\" and \"Acked-by:\" over \"Acked-By\".\n+\n [[git-tools]]\n === Generate your patch using Git tools out of your commits.\n \n-- \ngitgitgadget\n\n"},{"id":"485940","messageId":"cdb5fd0957fee7ce8c19720f588da96898cd3dc9.1703176866.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v2.git.1703176865.gitgitgadget@gmail.com","subject":"[PATCH v2 7/9] SubmittingPatches: clarify GitHub visual","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-21T16:41:03Z","receivedAt":"2023-12-21T16:41:14Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nGitHub has two general forms for its states, sometimes they're a simple\ncolored object (e.g. green check or red x), and sometimes there's also a\ncolored container (e.g. green box or red circle) with containing that\nobject (e.g. check or x).\n\nThat's a lot of words to try to describe things, but in general, the key\nfor a failure is that it's recognized as an `x` and that it's associated\nwith the color red -- the color of course is problematic for people who\nare red-green color-blind, but that's why they are paired with distinct\nshapes.\n\nUsing the term `cross` doesn't really help.\n\nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 4476b52a50f..8f79253c5cb 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -603,7 +603,7 @@ to your fork of Git on GitHub. You can monitor the test state of all your\n branches here: `https://github.com//git/actions/workflows/main.yml`\n \n If a branch did not pass all test cases then it is marked with a red\n-cross. In that case you can click on the failing job and navigate to\n++x+. In that case you can click on the failing job and navigate to\n \"ci/run-build-and-tests.sh\" and/or \"ci/print-test-failures.sh\". You\n can also download \"Artifacts\" which are tarred (or zipped) archives\n with test data relevant for debugging.\n-- \ngitgitgadget\n\n"},{"id":"485942","messageId":"77576327df8710efad73487f4be79e6801bc1fd3.1703176866.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v2.git.1703176865.gitgitgadget@gmail.com","subject":"[PATCH v2 8/9] SubmittingPatches: clarify GitHub artifact format","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-21T16:41:04Z","receivedAt":"2023-12-21T16:41:15Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nGitHub wraps artifacts generated by workflows in a .zip file.\n\nInternally, workflows can package anything they like in them.\n\nA recently generated failure artifact had the form:\n\nwindows-artifacts.zip\n Length Date Time Name\n--------- ---------- ----- ----\n 76001695 12-19-2023 01:35 artifacts.tar.gz\n 11005650 12-19-2023 01:35 tracked.tar.gz\n--------- -------\n 87007345 2 files\n\nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 8f79253c5cb..cb0dcce6a17 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -605,7 +605,8 @@ branches here: `https://github.com//git/actions/workflows/ma\n If a branch did not pass all test cases then it is marked with a red\n +x+. In that case you can click on the failing job and navigate to\n \"ci/run-build-and-tests.sh\" and/or \"ci/print-test-failures.sh\". You\n-can also download \"Artifacts\" which are tarred (or zipped) archives\n+can also download \"Artifacts\" which are zip archives containing\n+tarred (or zipped) archives\n with test data relevant for debugging.\n \n Then fix the problem and push your fix to your GitHub fork. This will\n-- \ngitgitgadget\n\n"},{"id":"485941","messageId":"a4878f58fe487460bdcf94e6de08e2d03c3bfa5e.1703176866.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v2.git.1703176865.gitgitgadget@gmail.com","subject":"[PATCH v2 9/9] SubmittingPatches: hyphenate non-ASCII","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-21T16:41:05Z","receivedAt":"2023-12-21T16:41:16Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nGit documentation does this with the exception of ancient release notes.\n\nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex cb0dcce6a17..9283eb0ef71 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -699,7 +699,7 @@ message to an external program, and this is a handy way to drive\n `git am`. However, if the message is MIME encoded, what is\n piped into the program is the representation you see in your\n `*Article*` buffer after unwrapping MIME. This is often not what\n-you would want for two reasons. It tends to screw up non ASCII\n+you would want for two reasons. It tends to screw up non-ASCII\n characters (most notably in people's names), and also\n whitespaces (fatal in patches). Running \"C-u g\" to display the\n message in raw form before using \"|\" to run the pipe can work\n-- \ngitgitgadget\n"},{"id":"485952","messageId":"xmqqplyzl1e8.fsf@gitster.g","threadId":"60631","inReplyTo":"c0db8336e519cb43767effbe842dc8b97f914a4b.1703176866.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 2/9] CodingGuidelines: write punctuation marks","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-21T20:57:19Z","receivedAt":"2023-12-21T20:57:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Josh Soref via GitGitGadget\" writes:\n\nNobody seems to have commented on this step in the previous round,\nbut I do not understand what you mean by ...\n\n> From: Josh Soref \n>\n> - Match style in Release Notes\n\n... at all. The patch text is fine, though.\n\n> Signed-off-by: Josh Soref \n> ---\n> Documentation/CodingGuidelines | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\n> index af94ed3a75d..578587a4715 100644\n> --- a/Documentation/CodingGuidelines\n> +++ b/Documentation/CodingGuidelines\n> @@ -578,7 +578,7 @@ Externally Visible Names\n> . The variable name describes the effect of tweaking this knob.\n> \n> The section and variable names that consist of multiple words are\n> - formed by concatenating the words without punctuations (e.g. `-`),\n> + formed by concatenating the words without punctuation marks (e.g. `-`),\n> and are broken using bumpyCaps in documentation as a hint to the\n> reader.\n"},{"id":"485954","messageId":"xmqqedffl13r.fsf@gitster.g","threadId":"60631","inReplyTo":"b9a8eb6aa4e87cd96fbf2b5d514350508076d756.1703176866.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 1/9] CodingGuidelines: move period inside parentheses","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-21T21:03:36Z","receivedAt":"2023-12-21T21:03:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Josh Soref via GitGitGadget\" writes:\n\n> From: Josh Soref \n>\n> The contents within parenthesis should be omittable without resulting\n> in broken text.\n>\n> Eliding the parenthesis left a period to end a run without any content.\n\nNobody seems to have commented on this one in the previous round,\nbut quite honestly, for this particular instance, I suspect that it\nmay become easier to read if we just lost these parentheses, as the\nnext sentence \"You do not have to include more than ...\" is just a\nbit of extra material to support the first sentence like the one we\nsee in the parentheses. Alternatively, moving that \"You do not have\nto\" also inside the same parentheses might work slightly better.\n\nIt might be even easier to follow if we moved the list of \"approved\nheaders\" (and the \"You do not have to ... more than one\" note that\nsupports the \"currently approved list\") totally out of line by\nmaking it a side note.\n\n> Signed-off-by: Josh Soref \n> ---\n> Documentation/CodingGuidelines | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\n> index 8ed517a5ca0..af94ed3a75d 100644\n> --- a/Documentation/CodingGuidelines\n> +++ b/Documentation/CodingGuidelines\n> @@ -450,7 +450,7 @@ For C programs:\n> one of the approved headers that includes it first for you. (The\n> approved headers currently include \"builtin.h\",\n> \"t/helper/test-tool.h\", \"xdiff/xinclude.h\", or\n> - \"reftable/system.h\"). You do not have to include more than one of\n> + \"reftable/system.h\".) You do not have to include more than one of\n> these.\n> \n> - A C file must directly include the header files that declare the\n"},{"id":"485955","messageId":"xmqqa5q3l0tn.fsf@gitster.g","threadId":"60631","inReplyTo":"22d66c5b78a6930e195141df848266cac099ca08.1703176866.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 3/9] SubmittingPatches: drop ref to \"What's in git.git\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-21T21:09:40Z","receivedAt":"2023-12-21T21:09:51Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Josh Soref via GitGitGadget\" writes:\n\n> From: Josh Soref \n>\n> \"What's in git.git\" was last seen in 2010:\n> https://lore.kernel.org/git/?q=%22what%27s+in+git.git%22\n> https://lore.kernel.org/git/7vaavikg72.fsf@alter.siamese.dyndns.org/\n>\n> Signed-off-by: Josh Soref \n> ---\n> Documentation/SubmittingPatches | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n\nThanks. I stopped doing these long time ago, as there were certain\noverlaps with \"What's cooking\" that lists the topics that have\ngraduated in a separate section.\n\n>\n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> index bce7f97815c..32e90238777 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -570,7 +570,7 @@ their trees themselves.\n> master).\n> \n> * Read the Git mailing list, the maintainer regularly posts messages\n> - entitled \"What's cooking in git.git\" and \"What's in git.git\" giving\n> + entitled \"What's cooking in git.git\" giving\n> the status of various proposed changes.\n> \n> == GitHub CI[[GHCI]]\n"},{"id":"485956","messageId":"xmqq4jgbl0iz.fsf@gitster.g","threadId":"60631","inReplyTo":"8848572fe2c7432ede85e042bc2558fd8b3e8b1d.1703176866.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 5/9] SubmittingPatches: update extra tags list","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-21T21:16:04Z","receivedAt":"2023-12-21T21:16:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Josh Soref via GitGitGadget\" writes:\n\n> +. `Co-authored-by:` is used to indicate that people exchanged drafts\n> + of a patch before submitting it.\n\nI am afraid this misses the essence of what Co-authoring means.\nYou may have shared your draft as FYI to your colleagues, and they\nmay have tweaked phrasing and responded with their reviews to help\nyou improve _your_ work, but that may not make them your Co-authors.\n\nI think the \"intent\" counts more. If people closely worked\ntogether, exchanging drafts and agreeing on the final version among\nthemselves before submitting, with the understanding that they share\nthe authorship credit/blame, they are Co-authors.\n\n> +. `Helped-by:` is used to credit someone who suggested ideas for\n> + changes without providing the precise changes in patch form.\n> +. `Mentored-by:` is used to credit someone with helping develop a\n> + patch as part of a mentorship program (e.g., GSoC or Outreachy).\n\nNicely differentiated.\n\n"},{"id":"485957","messageId":"xmqqzfy3jlv1.fsf@gitster.g","threadId":"60631","inReplyTo":"8f16c7caa7366cab22ad332c402f80823add8224.1703176866.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 6/9] SubmittingPatches: improve extra tags advice","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-21T21:18:10Z","receivedAt":"2023-12-21T21:18:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Josh Soref via GitGitGadget\" writes:\n\n> From: Josh Soref \n>\n> Current statistics show a strong preference to only capitalize the first\n> letter in a hyphenated tag, but that some guidance would be helpful:\n>\n> git log |\n> perl -ne 'next unless /^\\s+(?:Signed-[oO]ff|Acked)-[bB]y:/;\n> s/^\\s+//;s/:.*/:/;print'|\n> sort|uniq -c|sort -n\n> 2 Signed-off-By:\n> 4 Signed-Off-by:\n> 22 Acked-By:\n> 47 Signed-Off-By:\n> 2202 Acked-by:\n> 95315 Signed-off-by:\n>\n> Signed-off-by: Josh Soref \n> ---\n> Documentation/SubmittingPatches | 3 +++\n> 1 file changed, 3 insertions(+)\n>\n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> index 31878cb70b7..4476b52a50f 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -368,6 +368,9 @@ While you can also create your own trailer if the situation warrants it, we\n> encourage you to instead use one of the common trailers in this project\n> highlighted above.\n> \n> +Extra tags should only capitalize the very first letter, i.e. favor\n> +\"Signed-off-by\" over \"Signed-Off-By\" and \"Acked-by:\" over \"Acked-By\".\n\nDrop \"Extra\", perhaps? The sentence before already discourages any\nextra ones, and what this sentence teaches the contributors is to\navoud spelling variation when to spell the common ones.\n\n> [[git-tools]]\n> === Generate your patch using Git tools out of your commits.\n"},{"id":"485958","messageId":"xmqqv88rjleu.fsf@gitster.g","threadId":"60631","inReplyTo":"cdb5fd0957fee7ce8c19720f588da96898cd3dc9.1703176866.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 7/9] SubmittingPatches: clarify GitHub visual","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-21T21:27:53Z","receivedAt":"2023-12-21T21:27:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Josh Soref via GitGitGadget\" writes:\n\n> From: Josh Soref \n>\n> GitHub has two general forms for its states, sometimes they're a simple\n> colored object (e.g. green check or red x), and sometimes there's also a\n> colored container (e.g. green box or red circle) with containing that\n> object (e.g. check or x).\n>\n> That's a lot of words to try to describe things, but in general, the key\n> for a failure is that it's recognized as an `x` and that it's associated\n> with the color red -- the color of course is problematic for people who\n> are red-green color-blind, but that's why they are paired with distinct\n> shapes.\n>\n> Using the term `cross` doesn't really help.\n\nI am not sure if this is accurate. Using `x` alone does not help,\neither.\n\nI think this was raised during the review of the initial round, but\n...\n\n> If a branch did not pass all test cases then it is marked with a red\n> -cross. In that case you can click on the failing job and navigate to\n> ++x+. In that case you can click on the failing job and navigate to\n\n... it would help if we added something like \", instead of a green\ncheckmark\" after \"with a red x\". It will make the contrast with the\nsucceeding case stronger. IOW, we can take advantage of the idea to\nuse \"pair with distinct shapes and colors\" ourselves.\n\n> \"ci/run-build-and-tests.sh\" and/or \"ci/print-test-failures.sh\". You\n> can also download \"Artifacts\" which are tarred (or zipped) archives\n> with test data relevant for debugging.\n"},{"id":"485962","messageId":"CACZqfqAtT_M8T3AxbgZrkgi3GtQ=JZLu4wvh3O0C9dFvCU3rWg@mail.gmail.com","threadId":"60631","inReplyTo":"xmqqplyzl1e8.fsf@gitster.g","subject":"Re: [PATCH v2 2/9] CodingGuidelines: write punctuation marks","fromName":"Josh Soref","fromEmail":"jsoref@gmail.com","sentAt":"2023-12-21T21:46:08Z","receivedAt":"2023-12-21T21:46:21Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"Junio C Hamano wrote:\n> Nobody seems to have commented on this step in the previous round,\n> but I do not understand what you mean by ...\n>\n> > From: Josh Soref \n> > - Match style in Release Notes\n>\n> ... at all. The patch text is fine, though.\n\nhttps://github.com/gitgitgadget/git/blob/692be87cbba55e8488f805d236f2ad50483bd7d5/Documentation/RelNotes/2.43.0.txt#L221\n"},{"id":"485963","messageId":"CACZqfqCzJf5q2xcfPT3C0YAWS0qNxyQvYikisDokQ5Dw-ZFMww@mail.gmail.com","threadId":"60631","inReplyTo":"xmqqedffl13r.fsf@gitster.g","subject":"Re: [PATCH v2 1/9] CodingGuidelines: move period inside parentheses","fromName":"Josh Soref","fromEmail":"jsoref@gmail.com","sentAt":"2023-12-21T21:52:57Z","receivedAt":"2023-12-21T21:53:11Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"Junio C Hamano wrote:\n> > From: Josh Soref \n> >\n> > The contents within parenthesis should be omittable without resulting\n> > in broken text.\n> >\n> > Eliding the parenthesis left a period to end a run without any content.\n>\n> Nobody seems to have commented on this one in the previous round,\n> but quite honestly, for this particular instance, I suspect that it\n> may become easier to read if we just lost these parentheses, as the\n> next sentence \"You do not have to include more than ...\" is just a\n> bit of extra material to support the first sentence like the one we\n> see in the parentheses. Alternatively, moving that \"You do not have\n> to\" also inside the same parentheses might work slightly better.\n\n> It might be even easier to follow if we moved the list of \"approved\n> headers\" (and the \"You do not have to ... more than one\" note that\n> supports the \"currently approved list\") totally out of line by\n> making it a side note.\n\nI think, in principle, it'd be better if it was its own thing, but the\nstructure of this entire section makes this really hard -- I certainly\ncan't imagine a way to do it.\n\nThe laziest fix is:\n\n- The first #include in C files, except in platform specific compat/\nimplementations and sha1dc/, must be one of \"git-compat-util.h\",\n\"builtin.h\", \"t/helper/test-tool.h\", \"xdiff/xinclude.h\", or\n\"reftable/system.h\".\n\nBeyond that, I don't understand how to parse:\n You do not have to include more than one of these.\n\n(Sorry, I'd like to be slightly ignorant of the C parts of git --\nlet's ignore that I've been blamed for at least one change to them --\nso, I'm not going to look.)\n"},{"id":"485964","messageId":"CACZqfqBWKepr7A2O8Wp_8FqD5h9=O6kQUqEjN8Z1fOdks1TYPA@mail.gmail.com","threadId":"60631","inReplyTo":"xmqq4jgbl0iz.fsf@gitster.g","subject":"Re: [PATCH v2 5/9] SubmittingPatches: update extra tags list","fromName":"Josh Soref","fromEmail":"jsoref@gmail.com","sentAt":"2023-12-21T21:55:24Z","receivedAt":"2023-12-21T21:55:58Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"Junio C Hamano wrote:\n> \"Josh Soref via GitGitGadget\" writes:\n>\n> > +. `Co-authored-by:` is used to indicate that people exchanged drafts\n> > + of a patch before submitting it.\n>\n> I am afraid this misses the essence of what Co-authoring means.\n> You may have shared your draft as FYI to your colleagues, and they\n> may have tweaked phrasing and responded with their reviews to help\n> you improve _your_ work, but that may not make them your Co-authors.\n>\n> I think the \"intent\" counts more. If people closely worked\n> together, exchanging drafts and agreeing on the final version among\n> themselves before submitting, with the understanding that they share\n> the authorship credit/blame, they are Co-authors.\n\n. `Co-authored-by:` is used to indicate that people collaborated on the\n contents of a patch before submitting it.\n\n?\n"},{"id":"485965","messageId":"xmqqr0jfjk1s.fsf@gitster.g","threadId":"60631","inReplyTo":"CACZqfqAtT_M8T3AxbgZrkgi3GtQ=JZLu4wvh3O0C9dFvCU3rWg@mail.gmail.com","subject":"Re: [PATCH v2 2/9] CodingGuidelines: write punctuation marks","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-21T21:57:19Z","receivedAt":"2023-12-21T21:57:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Josh Soref writes:\n\n> Junio C Hamano wrote:\n>> Nobody seems to have commented on this step in the previous round,\n>> but I do not understand what you mean by ...\n>>\n>> > From: Josh Soref \n>> > - Match style in Release Notes\n>>\n>> ... at all. The patch text is fine, though.\n>\n> https://github.com/gitgitgadget/git/blob/692be87cbba55e8488f805d236f2ad50483bd7d5/Documentation/RelNotes/2.43.0.txt#L221\n\nYou mean just a single mention of the phrase? If so, you should\npinpoint it, e.g. \"The release notes for Git 2.43 calls them\n'punctuation marks', so let's use that here, too\" or something like\nthat.\n\nUnless you are sure that all the issues of Release Notes have and\nwill consistently say \"punctuation marks\" and never say\n\"punctuations\", that is.\n"},{"id":"485970","messageId":"b3b03da0e33b805f1f420a0dc1a19d86@manjaro.org","threadId":"60631","inReplyTo":"xmqqedffl13r.fsf@gitster.g","subject":"Re: [PATCH v2 1/9] CodingGuidelines: move period inside parentheses","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2023-12-22T01:30:01Z","receivedAt":"2023-12-22T01:30:03Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"On 2023-12-21 22:03, Junio C Hamano wrote:\n> \"Josh Soref via GitGitGadget\" writes:\n> \n>> From: Josh Soref \n>> \n>> The contents within parenthesis should be omittable without resulting\n>> in broken text.\n>> \n>> Eliding the parenthesis left a period to end a run without any \n>> content.\n> \n> Nobody seems to have commented on this one in the previous round,\n> but quite honestly, for this particular instance, I suspect that it\n> may become easier to read if we just lost these parentheses, as the\n> next sentence \"You do not have to include more than ...\" is just a\n> bit of extra material to support the first sentence like the one we\n> see in the parentheses. Alternatively, moving that \"You do not have\n> to\" also inside the same parentheses might work slightly better.\n\nI agree with simply erasing the parentheses, it makes the paragraph flow \nmuch better.\n\n> It might be even easier to follow if we moved the list of \"approved\n> headers\" (and the \"You do not have to ... more than one\" note that\n> supports the \"currently approved list\") totally out of line by\n> making it a side note.\n> \n>> Signed-off-by: Josh Soref \n>> ---\n>> Documentation/CodingGuidelines | 2 +-\n>> 1 file changed, 1 insertion(+), 1 deletion(-)\n>> \n>> diff --git a/Documentation/CodingGuidelines \n>> b/Documentation/CodingGuidelines\n>> index 8ed517a5ca0..af94ed3a75d 100644\n>> --- a/Documentation/CodingGuidelines\n>> +++ b/Documentation/CodingGuidelines\n>> @@ -450,7 +450,7 @@ For C programs:\n>> one of the approved headers that includes it first for you. (The\n>> approved headers currently include \"builtin.h\",\n>> \"t/helper/test-tool.h\", \"xdiff/xinclude.h\", or\n>> - \"reftable/system.h\"). You do not have to include more than one of\n>> + \"reftable/system.h\".) You do not have to include more than one of\n>> these.\n>> \n>> - A C file must directly include the header files that declare the\n"},{"id":"486068","messageId":"pull.1623.v3.git.1703739324.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v2.git.1703176865.gitgitgadget@gmail.com","subject":"[PATCH v3 0/9] Minor improvements to CodingGuidelines and SubmittingPatches","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-28T04:55:15Z","receivedAt":"2023-12-28T04:55:28Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"These are a bunch of things I've run into over my past couple of attempts to\ncontribute to Git.\n\n * Incremental punctuation/grammatical improvements\n * Update extra tags suggestions based on common usage\n * drop reference to an article that was discontinued over a decade ago\n * update GitHub references\n * harmonize non-ASCII while I'm here\n\nNote that I'm trying to do things \"in the neighborhood\". It'll be slower\nthan me replacing things topically, but hopefully easier for others to\ndigest. My current estimate is a decade or two :).\n\nJosh Soref (9):\n CodingGuidelines: move period inside parentheses\n CodingGuidelines: write punctuation marks\n SubmittingPatches: drop ref to \"What's in git.git\"\n SubmittingPatches: discourage new trailers\n SubmittingPatches: update extra tags list\n SubmittingPatches: provide tag naming advice\n SubmittingPatches: clarify GitHub visual\n SubmittingPatches: clarify GitHub artifact format\n SubmittingPatches: hyphenate non-ASCII\n\n Documentation/CodingGuidelines | 4 ++--\n Documentation/SubmittingPatches | 33 +++++++++++++++++++++++----------\n 2 files changed, 25 insertions(+), 12 deletions(-)\n\n\nbase-commit: 624eb90fa8f65a79396615f3c2842ac5a3743350\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1623%2Fjsoref%2Fdocumentation-v3\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1623/jsoref/documentation-v3\nPull-Request: https://github.com/gitgitgadget/git/pull/1623\n\nRange-diff vs v2:\n\n 1: b9a8eb6aa4e = 1: b9a8eb6aa4e CodingGuidelines: move period inside parentheses\n 2: c0db8336e51 = 2: c0db8336e51 CodingGuidelines: write punctuation marks\n 3: 22d66c5b78a = 3: 22d66c5b78a SubmittingPatches: drop ref to \"What's in git.git\"\n 4: eac2211332f = 4: eac2211332f SubmittingPatches: discourage new trailers\n 5: 8848572fe2c = 5: 8848572fe2c SubmittingPatches: update extra tags list\n 6: 8f16c7caa73 ! 6: f28c1011ba9 SubmittingPatches: improve extra tags advice\n @@ Metadata\n Author: Josh Soref \n \n ## Commit message ##\n - SubmittingPatches: improve extra tags advice\n + SubmittingPatches: provide tag naming advice\n \n Current statistics show a strong preference to only capitalize the first\n letter in a hyphenated tag, but that some guidance would be helpful:\n @@ Documentation/SubmittingPatches: While you can also create your own trailer if t\n encourage you to instead use one of the common trailers in this project\n highlighted above.\n \n -+Extra tags should only capitalize the very first letter, i.e. favor\n ++Only capitalize the very first letter of tags, i.e. favor\n +\"Signed-off-by\" over \"Signed-Off-By\" and \"Acked-by:\" over \"Acked-By\".\n +\n [[git-tools]]\n 7: cdb5fd0957f < -: ----------- SubmittingPatches: clarify GitHub visual\n 8: 77576327df8 ! 7: 49cef6f7c20 SubmittingPatches: clarify GitHub artifact format\n @@ Metadata\n Author: Josh Soref \n \n ## Commit message ##\n - SubmittingPatches: clarify GitHub artifact format\n + SubmittingPatches: clarify GitHub visual\n \n - GitHub wraps artifacts generated by workflows in a .zip file.\n + GitHub has two general forms for its states, sometimes they're a simple\n + colored object (e.g. green check or red x), and sometimes there's also a\n + colored container (e.g. green box or red circle) which contains that\n + object (e.g. check or x).\n \n - Internally, workflows can package anything they like in them.\n -\n - A recently generated failure artifact had the form:\n -\n - windows-artifacts.zip\n - Length Date Time Name\n - --------- ---------- ----- ----\n - 76001695 12-19-2023 01:35 artifacts.tar.gz\n - 11005650 12-19-2023 01:35 tracked.tar.gz\n - --------- -------\n - 87007345 2 files\n + That's a lot of words to try to describe things, but in general, the key\n + for a failure is that it's recognized as an `x` and that it's associated\n + with the color red -- the color of course is problematic for people who\n + are red-green color-blind, but that's why they are paired with distinct\n + shapes.\n \n Signed-off-by: Josh Soref \n \n ## Documentation/SubmittingPatches ##\n -@@ Documentation/SubmittingPatches: branches here: `https://github.com//git/actions/workflows/ma\n - If a branch did not pass all test cases then it is marked with a red\n - +x+. In that case you can click on the failing job and navigate to\n - \"ci/run-build-and-tests.sh\" and/or \"ci/print-test-failures.sh\". You\n +@@ Documentation/SubmittingPatches: After the initial setup, CI will run whenever you push new changes\n + to your fork of Git on GitHub. You can monitor the test state of all your\n + branches here: `https://github.com//git/actions/workflows/main.yml`\n + \n +-If a branch did not pass all test cases then it is marked with a red\n +-cross. In that case you can click on the failing job and navigate to\n +-\"ci/run-build-and-tests.sh\" and/or \"ci/print-test-failures.sh\". You\n -can also download \"Artifacts\" which are tarred (or zipped) archives\n -+can also download \"Artifacts\" which are zip archives containing\n -+tarred (or zipped) archives\n - with test data relevant for debugging.\n +-with test data relevant for debugging.\n ++If a branch does not pass all test cases then it will be marked with a\n ++red +x+, instead of a green check. In that case, you can click on the\n ++failing job and navigate to \"ci/run-build-and-tests.sh\" and/or\n ++\"ci/print-test-failures.sh\". You can also download \"Artifacts\" which\n ++are tarred (or zipped) archives with test data relevant for debugging.\n \n Then fix the problem and push your fix to your GitHub fork. This will\n + trigger a new CI build to ensure all tests pass.\n -: ----------- > 8: deb1bf02f3a SubmittingPatches: clarify GitHub artifact format\n 9: a4878f58fe4 = 9: b1b75cc6a3e SubmittingPatches: hyphenate non-ASCII\n\n-- \ngitgitgadget\n"},{"id":"486069","messageId":"b9a8eb6aa4e87cd96fbf2b5d514350508076d756.1703739324.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v3.git.1703739324.gitgitgadget@gmail.com","subject":"[PATCH v3 1/9] CodingGuidelines: move period inside parentheses","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-28T04:55:16Z","receivedAt":"2023-12-28T04:55:29Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nThe contents within parenthesis should be omittable without resulting\nin broken text.\n\nEliding the parenthesis left a period to end a run without any content.\n\nSigned-off-by: Josh Soref \n---\n Documentation/CodingGuidelines | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 8ed517a5ca0..af94ed3a75d 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -450,7 +450,7 @@ For C programs:\n one of the approved headers that includes it first for you. (The\n approved headers currently include \"builtin.h\",\n \"t/helper/test-tool.h\", \"xdiff/xinclude.h\", or\n- \"reftable/system.h\"). You do not have to include more than one of\n+ \"reftable/system.h\".) You do not have to include more than one of\n these.\n \n - A C file must directly include the header files that declare the\n-- \ngitgitgadget\n\n"},{"id":"486070","messageId":"c0db8336e519cb43767effbe842dc8b97f914a4b.1703739324.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v3.git.1703739324.gitgitgadget@gmail.com","subject":"[PATCH v3 2/9] CodingGuidelines: write punctuation marks","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-28T04:55:17Z","receivedAt":"2023-12-28T04:55:30Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\n- Match style in Release Notes\n\nSigned-off-by: Josh Soref \n---\n Documentation/CodingGuidelines | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex af94ed3a75d..578587a4715 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -578,7 +578,7 @@ Externally Visible Names\n . The variable name describes the effect of tweaking this knob.\n \n The section and variable names that consist of multiple words are\n- formed by concatenating the words without punctuations (e.g. `-`),\n+ formed by concatenating the words without punctuation marks (e.g. `-`),\n and are broken using bumpyCaps in documentation as a hint to the\n reader.\n \n-- \ngitgitgadget\n\n"},{"id":"486071","messageId":"22d66c5b78a6930e195141df848266cac099ca08.1703739324.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v3.git.1703739324.gitgitgadget@gmail.com","subject":"[PATCH v3 3/9] SubmittingPatches: drop ref to \"What's in git.git\"","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-28T04:55:18Z","receivedAt":"2023-12-28T04:55:31Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\n\"What's in git.git\" was last seen in 2010:\n https://lore.kernel.org/git/?q=%22what%27s+in+git.git%22\n https://lore.kernel.org/git/7vaavikg72.fsf@alter.siamese.dyndns.org/\n\nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex bce7f97815c..32e90238777 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -570,7 +570,7 @@ their trees themselves.\n master).\n \n * Read the Git mailing list, the maintainer regularly posts messages\n- entitled \"What's cooking in git.git\" and \"What's in git.git\" giving\n+ entitled \"What's cooking in git.git\" giving\n the status of various proposed changes.\n \n == GitHub CI[[GHCI]]\n-- \ngitgitgadget\n\n"},{"id":"486072","messageId":"eac2211332f754c5f4127a58aafb9882bfe939e8.1703739324.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v3.git.1703739324.gitgitgadget@gmail.com","subject":"[PATCH v3 4/9] SubmittingPatches: discourage new trailers","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-28T04:55:19Z","receivedAt":"2023-12-28T04:55:32Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nThere seems to be consensus amongst the core Git community on a working\nset of common trailers, and there are non-trivial costs to people\ninventing new trailers (research to discover what they mean/how they\ndiffer from existing trailers) such that inventing new ones is generally\nunwarranted and not something to be recommended to new contributors.\n\nSuggested-by: Elijah Newren \nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 32e90238777..58dfe405049 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -356,8 +356,9 @@ If you like, you can put extra tags at the end:\n . `Tested-by:` is used to indicate that the person applied the patch\n and found it to have the desired effect.\n \n-You can also create your own tag or use one that's in common usage\n-such as \"Thanks-to:\", \"Based-on-patch-by:\", or \"Mentored-by:\".\n+While you can also create your own trailer if the situation warrants it, we\n+encourage you to instead use one of the common trailers in this project\n+highlighted above.\n \n [[git-tools]]\n === Generate your patch using Git tools out of your commits.\n-- \ngitgitgadget\n\n"},{"id":"486073","messageId":"8848572fe2c7432ede85e042bc2558fd8b3e8b1d.1703739324.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v3.git.1703739324.gitgitgadget@gmail.com","subject":"[PATCH v3 5/9] SubmittingPatches: update extra tags list","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-28T04:55:20Z","receivedAt":"2023-12-28T04:55:33Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nAdd items with at least 100 uses in the past three years:\n- Co-authored-by\n- Helped-by\n- Mentored-by\n- Suggested-by\n\ngit log --since=3.years|\n perl -ne 'next unless /^\\s+[A-Z][a-z]+-\\S+:/;s/^\\s+//;s/:.*/:/;print'|\n sort|uniq -c|sort -n|grep '[0-9][0-9] '\n 14 Based-on-patch-by:\n 14 Original-patch-by:\n 17 Tested-by:\n 100 Suggested-by:\n 121 Co-authored-by:\n 163 Mentored-by:\n 274 Reported-by:\n 290 Acked-by:\n 450 Helped-by:\n 602 Reviewed-by:\n14111 Signed-off-by:\n\nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 58dfe405049..31878cb70b7 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -355,6 +355,14 @@ If you like, you can put extra tags at the end:\n patch after a detailed analysis.\n . `Tested-by:` is used to indicate that the person applied the patch\n and found it to have the desired effect.\n+. `Co-authored-by:` is used to indicate that people exchanged drafts\n+ of a patch before submitting it.\n+. `Helped-by:` is used to credit someone who suggested ideas for\n+ changes without providing the precise changes in patch form.\n+. `Mentored-by:` is used to credit someone with helping develop a\n+ patch as part of a mentorship program (e.g., GSoC or Outreachy).\n+. `Suggested-by:` is used to credit someone with suggesting the idea\n+ for a patch.\n \n While you can also create your own trailer if the situation warrants it, we\n encourage you to instead use one of the common trailers in this project\n-- \ngitgitgadget\n\n"},{"id":"486074","messageId":"f28c1011ba91ce6ddcf09346c59cbc2b06c68ffc.1703739324.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v3.git.1703739324.gitgitgadget@gmail.com","subject":"[PATCH v3 6/9] SubmittingPatches: provide tag naming advice","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-28T04:55:21Z","receivedAt":"2023-12-28T04:55:34Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nCurrent statistics show a strong preference to only capitalize the first\nletter in a hyphenated tag, but that some guidance would be helpful:\n\ngit log |\n perl -ne 'next unless /^\\s+(?:Signed-[oO]ff|Acked)-[bB]y:/;\n s/^\\s+//;s/:.*/:/;print'|\n sort|uniq -c|sort -n\n 2 Signed-off-By:\n 4 Signed-Off-by:\n 22 Acked-By:\n 47 Signed-Off-By:\n2202 Acked-by:\n95315 Signed-off-by:\n\nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 31878cb70b7..94c874ab5e6 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -368,6 +368,9 @@ While you can also create your own trailer if the situation warrants it, we\n encourage you to instead use one of the common trailers in this project\n highlighted above.\n \n+Only capitalize the very first letter of tags, i.e. favor\n+\"Signed-off-by\" over \"Signed-Off-By\" and \"Acked-by:\" over \"Acked-By\".\n+\n [[git-tools]]\n === Generate your patch using Git tools out of your commits.\n \n-- \ngitgitgadget\n\n"},{"id":"486075","messageId":"49cef6f7c20d79ef217b345364ce9f7143bf7b7d.1703739324.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v3.git.1703739324.gitgitgadget@gmail.com","subject":"[PATCH v3 7/9] SubmittingPatches: clarify GitHub visual","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-28T04:55:22Z","receivedAt":"2023-12-28T04:55:35Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nGitHub has two general forms for its states, sometimes they're a simple\ncolored object (e.g. green check or red x), and sometimes there's also a\ncolored container (e.g. green box or red circle) which contains that\nobject (e.g. check or x).\n\nThat's a lot of words to try to describe things, but in general, the key\nfor a failure is that it's recognized as an `x` and that it's associated\nwith the color red -- the color of course is problematic for people who\nare red-green color-blind, but that's why they are paired with distinct\nshapes.\n\nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 10 +++++-----\n 1 file changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 94c874ab5e6..0665f89f38c 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -602,11 +602,11 @@ After the initial setup, CI will run whenever you push new changes\n to your fork of Git on GitHub. You can monitor the test state of all your\n branches here: `https://github.com//git/actions/workflows/main.yml`\n \n-If a branch did not pass all test cases then it is marked with a red\n-cross. In that case you can click on the failing job and navigate to\n-\"ci/run-build-and-tests.sh\" and/or \"ci/print-test-failures.sh\". You\n-can also download \"Artifacts\" which are tarred (or zipped) archives\n-with test data relevant for debugging.\n+If a branch does not pass all test cases then it will be marked with a\n+red +x+, instead of a green check. In that case, you can click on the\n+failing job and navigate to \"ci/run-build-and-tests.sh\" and/or\n+\"ci/print-test-failures.sh\". You can also download \"Artifacts\" which\n+are tarred (or zipped) archives with test data relevant for debugging.\n \n Then fix the problem and push your fix to your GitHub fork. This will\n trigger a new CI build to ensure all tests pass.\n-- \ngitgitgadget\n\n"},{"id":"486076","messageId":"deb1bf02f3a3b0977f22a0f2d9ff4b84ad3ad5f3.1703739324.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v3.git.1703739324.gitgitgadget@gmail.com","subject":"[PATCH v3 8/9] SubmittingPatches: clarify GitHub artifact format","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-28T04:55:23Z","receivedAt":"2023-12-28T04:55:36Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nGitHub wraps artifacts generated by workflows in a .zip file.\n\nInternally, workflows can package anything they like in them.\n\nA recently generated failure artifact had the form:\n\nwindows-artifacts.zip\n Length Date Time Name\n--------- ---------- ----- ----\n 76001695 12-19-2023 01:35 artifacts.tar.gz\n 11005650 12-19-2023 01:35 tracked.tar.gz\n--------- -------\n 87007345 2 files\n\nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 0665f89f38c..5e2e13b5e09 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -606,7 +606,8 @@ If a branch does not pass all test cases then it will be marked with a\n red +x+, instead of a green check. In that case, you can click on the\n failing job and navigate to \"ci/run-build-and-tests.sh\" and/or\n \"ci/print-test-failures.sh\". You can also download \"Artifacts\" which\n-are tarred (or zipped) archives with test data relevant for debugging.\n+are zip archives containing tarred (or zipped) archives with test data\n+relevant for debugging.\n \n Then fix the problem and push your fix to your GitHub fork. This will\n trigger a new CI build to ensure all tests pass.\n-- \ngitgitgadget\n\n"},{"id":"486077","messageId":"b1b75cc6a3e4b6829a60550b394456dcb2a6ee25.1703739324.git.gitgitgadget@gmail.com","threadId":"60631","inReplyTo":"pull.1623.v3.git.1703739324.gitgitgadget@gmail.com","subject":"[PATCH v3 9/9] SubmittingPatches: hyphenate non-ASCII","fromName":"Josh Soref via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-12-28T04:55:24Z","receivedAt":"2023-12-28T04:55:37Z","isPatch":true,"sender":{"key":"jsoref@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2119212?v=4"},"body":"From: Josh Soref \n\nGit documentation does this with the exception of ancient release notes.\n\nSigned-off-by: Josh Soref \n---\n Documentation/SubmittingPatches | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 5e2e13b5e09..e734a3f0f17 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -699,7 +699,7 @@ message to an external program, and this is a handy way to drive\n `git am`. However, if the message is MIME encoded, what is\n piped into the program is the representation you see in your\n `*Article*` buffer after unwrapping MIME. This is often not what\n-you would want for two reasons. It tends to screw up non ASCII\n+you would want for two reasons. It tends to screw up non-ASCII\n characters (most notably in people's names), and also\n whitespaces (fatal in patches). Running \"C-u g\" to display the\n message in raw form before using \"|\" to run the pipe can work\n-- \ngitgitgadget\n"}]}