[PATCH 0/8] Minor improvements to CodingGuidelines and SubmittingPatches

[PATCH 0/8] Minor improvements to CodingGuidelines and SubmittingPatches

[Josh Soref via GitGitGadget]

These are a bunch of things I've run into over my past couple of attempts to
contribute to Git.

 * Incremental punctuation/grammatical improvements
 * Update extra tags suggestions based on common usage
 * drop reference to an article that was discontinued over a decade ago
 * update GitHub references
 * harmonize non-ASCII while I'm here

Note that I'm trying to do things "in the neighborhood". It'll be slower
than me replacing things topically, but hopefully easier for others to
digest. My current estimate is a decade or two :).

Josh Soref (8):
  CodingGuidelines: move period inside parentheses
  CodingGuidelines: write punctuation marks
  SubmittingPatches: drop ref to "What's in git.git"
  SubmittingPatches: update extra tags list
  SubmittingPatches: improve extra tags advice
  SubmittingPatches: clarify GitHub visual
  SubmittingPatches: clarify GitHub artifact format
  SubmittingPatches: hyphenate non-ASCII

 Documentation/CodingGuidelines  |  4 ++--
 Documentation/SubmittingPatches | 24 +++++++++++++++++++-----
 2 files changed, 21 insertions(+), 7 deletions(-)


base-commit: 624eb90fa8f65a79396615f3c2842ac5a3743350
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1623%2Fjsoref%2Fdocumentation-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1623/jsoref/documentation-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1623
-- 
gitgitgadget

[PATCH 1/8] CodingGuidelines: move period inside parentheses

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

The contents within parenthesis should be omittable without resulting
in broken text.

Eliding the parenthesis left a period to end a run without any content.

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/CodingGuidelines | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 8ed517a5ca0..af94ed3a75d 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -450,7 +450,7 @@ For C programs:
    one of the approved headers that includes it first for you.  (The
    approved headers currently include "builtin.h",
    "t/helper/test-tool.h", "xdiff/xinclude.h", or
-   "reftable/system.h").  You do not have to include more than one of
+   "reftable/system.h".)  You do not have to include more than one of
    these.
 
  - A C file must directly include the header files that declare the
-- 
gitgitgadget

[PATCH 2/8] CodingGuidelines: write punctuation marks

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

- Match style in Release Notes

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/CodingGuidelines | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index af94ed3a75d..578587a4715 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -578,7 +578,7 @@ Externally Visible Names
    . The variable name describes the effect of tweaking this knob.
 
    The section and variable names that consist of multiple words are
-   formed by concatenating the words without punctuations (e.g. `-`),
+   formed by concatenating the words without punctuation marks (e.g. `-`),
    and are broken using bumpyCaps in documentation as a hint to the
    reader.
 
-- 
gitgitgadget

[PATCH 3/8] SubmittingPatches: drop ref to "What's in git.git"

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

"What's in git.git" was last seen in 2010:
  https://lore.kernel.org/git/?q=%22what%27s+in+git.git%22
  https://lore.kernel.org/git/7vaavikg72.fsf@alter.siamese.dyndns.org/

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index bce7f97815c..32e90238777 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -570,7 +570,7 @@ their trees themselves.
   master).
 
 * Read the Git mailing list, the maintainer regularly posts messages
-  entitled "What's cooking in git.git" and "What's in git.git" giving
+  entitled "What's cooking in git.git" giving
   the status of various proposed changes.
 
 == GitHub CI[[GHCI]]
-- 
gitgitgadget

[PATCH 4/8] SubmittingPatches: update extra tags list

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

Add items with at least 100 uses:
- Co-authored-by
- Helped-by
- Mentored-by
- Suggested-by

Updating the create suggestion to something less commonly used.

git log |
  perl -ne 'next unless /^\s+[A-Z][a-z]+-\S+:/;s/^\s+//;s/:.*/:/;print'|
  sort|uniq -c|sort -n|grep '[0-9][0-9] '
  11 Helped-By:
  13 Message-ID:
  14 Reported-By:
  22 Acked-By:
  27 Inspired-by:
  29 Requested-by:
  35 Original-patch-by:
  43 Contributions-by:
  47 Signed-Off-By:
  65 Based-on-patch-by:
  68 Thanks-to:
  88 Improved-by:
 145 Co-authored-by:
 171 Noticed-by:
 182 Tested-by:
 361 Suggested-by:
 469 Mentored-by:
1196 Reported-by:
1727 Helped-by:
2177 Reviewed-by:
2202 Acked-by:
95313 Signed-off-by:

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 32e90238777..694a7bafb68 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -348,6 +348,8 @@ If you like, you can put extra tags at the end:
 
 . `Reported-by:` is used to credit someone who found the bug that
   the patch attempts to fix.
+. `Noticed-by:` liked `Reported-by:` indicates someone who noticed
+  the item being fixed.
 . `Acked-by:` says that the person who is more familiar with the area
   the patch attempts to modify liked the patch.
 . `Reviewed-by:`, unlike the other tags, can only be offered by the
@@ -355,9 +357,17 @@ If you like, you can put extra tags at the end:
   patch after a detailed analysis.
 . `Tested-by:` is used to indicate that the person applied the patch
   and found it to have the desired effect.
+. `Co-authored-by:` is used to indicate that multiple people
+  contributed to the work of a patch.
+. `Helped-by:` is used to credit someone with helping develop a
+  patch.
+. `Mentored-by:` is used to credit someone with helping develop a
+  patch.
+. `Suggested-by:` is used to credit someone with suggesting the idea
+  for a patch.
 
 You can also create your own tag or use one that's in common usage
-such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
+such as "Thanks-to:", "Based-on-patch-by:", or "Improved-by:".
 
 [[git-tools]]
 === Generate your patch using Git tools out of your commits.
-- 
gitgitgadget

[PATCH 5/8] SubmittingPatches: improve extra tags advice

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

Current statistics show a strong preference to only capitalize the first
letter in a hyphenated tag, but that some guidance would be helpful:

git log |
  perl -ne 'next unless /^\s+(?:Signed-[oO]ff|Acked)-[bB]y:/;
    s/^\s+//;s/:.*/:/;print'|
  sort|uniq -c|sort -n
   2 Signed-off-By:
   4 Signed-Off-by:
  22 Acked-By:
  47 Signed-Off-By:
2202 Acked-by:
95315 Signed-off-by:

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 694a7bafb68..d7a84f59478 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -369,6 +369,9 @@ If you like, you can put extra tags at the end:
 You can also create your own tag or use one that's in common usage
 such as "Thanks-to:", "Based-on-patch-by:", or "Improved-by:".
 
+Extra tags should only capitalize the very first letter, i.e. favor
+"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By".
+
 [[git-tools]]
 === Generate your patch using Git tools out of your commits.
 
-- 
gitgitgadget

[PATCH 6/8] SubmittingPatches: clarify GitHub visual

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

Some people would expect a cross to be upright, and potentially have
unequal lengths...

GitHub uses a white x overlaying a solid red circle to indicate failure.

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index d7a84f59478..8e19c7f82e4 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -604,7 +604,7 @@ to your fork of Git on GitHub.  You can monitor the test state of all your
 branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml`
 
 If a branch did not pass all test cases then it is marked with a red
-cross. In that case you can click on the failing job and navigate to
++x+. In that case you can click on the failing job and navigate to
 "ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You
 can also download "Artifacts" which are tarred (or zipped) archives
 with test data relevant for debugging.
-- 
gitgitgadget

[PATCH 7/8] SubmittingPatches: clarify GitHub artifact format

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

GitHub wraps artifacts generated by workflows in a .zip file.

Internally workflows can package anything they like in them.

A recently generated failure artifact had the form:

windows-artifacts.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
 76001695  12-19-2023 01:35   artifacts.tar.gz
 11005650  12-19-2023 01:35   tracked.tar.gz
---------                     -------
 87007345                     2 files

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 8e19c7f82e4..b4fa52ae348 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -606,7 +606,8 @@ branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/ma
 If a branch did not pass all test cases then it is marked with a red
 +x+. In that case you can click on the failing job and navigate to
 "ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You
-can also download "Artifacts" which are tarred (or zipped) archives
+can also download "Artifacts" which are zip archives containing
+tarred (or zipped) archives
 with test data relevant for debugging.
 
 Then fix the problem and push your fix to your GitHub fork. This will
-- 
gitgitgadget

[PATCH 8/8] SubmittingPatches: hyphenate non-ASCII

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

Git documentation does this with the exception of ancient release notes.

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index b4fa52ae348..3c53592cfc8 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -700,7 +700,7 @@ message to an external program, and this is a handy way to drive
 `git am`.  However, if the message is MIME encoded, what is
 piped into the program is the representation you see in your
 `*Article*` buffer after unwrapping MIME.  This is often not what
-you would want for two reasons.  It tends to screw up non ASCII
+you would want for two reasons.  It tends to screw up non-ASCII
 characters (most notably in people's names), and also
 whitespaces (fatal in patches).  Running "C-u g" to display the
 message in raw form before using "|" to run the pipe can work
-- 
gitgitgadget

Re: [PATCH 6/8] SubmittingPatches: clarify GitHub visual

[René Scharfe]

Am 19.12.23 um 09:41 schrieb Josh Soref via GitGitGadget:
> From: Josh Soref <jsoref@gmail.com>
>
> Some people would expect a cross to be upright, and potentially have
> unequal lengths...

There are lots of types of crosses.  And while looking them up on
Wikipedia I learned today that an x-cross is called "saltire" in
English.  I only knew it as St. Andrew's cross before.

> GitHub uses a white x overlaying a solid red circle to indicate failure.

They call it "x-circle-fill"
(https://primer.github.io/octicons/x-circle-fill-16).

>
> Signed-off-by: Josh Soref <jsoref@gmail.com>
> ---
>  Documentation/SubmittingPatches | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index d7a84f59478..8e19c7f82e4 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -604,7 +604,7 @@ to your fork of Git on GitHub.  You can monitor the test state of all your
>  branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml`
>
>  If a branch did not pass all test cases then it is marked with a red
> -cross. In that case you can click on the failing job and navigate to
> ++x+. In that case you can click on the failing job and navigate to

In the commit message you say the x is white, here it's red, so what is
it?  IIUC the circle is red and the x-cross inside is the same color as
the background, i.e. white in light mode and black in dark mode.  No
idea how to express that in one word.  Perhaps "red circle containing
and x-cross"?

René

Re: [PATCH 4/8] SubmittingPatches: update extra tags list

[Phillip Wood]

Hi Josh

On 19/12/2023 08:41, Josh Soref via GitGitGadget wrote:
> From: Josh Soref <jsoref@gmail.com>
> 
> Add items with at least 100 uses:
> - Co-authored-by
> - Helped-by
> - Mentored-by
> - Suggested-by

Thanks for adding these, they are widely used and should be documented. 
The patch also adds a mention for "Noticed-by:" - I'm less convinced by 
the need for that as I explain below.

> Updating the create suggestion to something less commonly used.

I'm not quite sure I understand what you mean by this sentence.

> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 32e90238777..694a7bafb68 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -348,6 +348,8 @@ If you like, you can put extra tags at the end:
>   
>   . `Reported-by:` is used to credit someone who found the bug that
>     the patch attempts to fix.
> +. `Noticed-by:` liked `Reported-by:` indicates someone who noticed
> +  the item being fixed.

I wonder if we really need a separate "Noticed-by" footer in addition to 
"Reported-by". Personally I use the latter to acknowledge the person who 
reported the issue being fix regards of weather I'm fixing a bug or some 
other issue.

>   . `Acked-by:` says that the person who is more familiar with the area
>     the patch attempts to modify liked the patch.
>   . `Reviewed-by:`, unlike the other tags, can only be offered by the
> @@ -355,9 +357,17 @@ If you like, you can put extra tags at the end:
>     patch after a detailed analysis.
>   . `Tested-by:` is used to indicate that the person applied the patch
>     and found it to have the desired effect.
> +. `Co-authored-by:` is used to indicate that multiple people
> +  contributed to the work of a patch.

Junio's comments in [1] may be helpful here

     If co-authors closely worked together (possibly but not necessarily
     outside the public view), exchanging drafts and agreeing on the
     final version before sending it to the list, by one approving the
     other's final draft, Co-authored-by may be appropriate.

     I would prefer to see more use of Helped-by when suggestions for
     improvements were made, possibly but not necessarily in a concrete
     "squashable patch" form, the original author accepted before
     sending the new version out, and the party who made suggestions saw
     the updated version at the same time as the general public.

So I think we should be clear that "Co-authored-by:" means that multiple 
authors worked closely together on the patch, rather than just 
contributed to it.

[1] https://lore.kernel.org/git/xmqqmth8wwcf.fsf@gitster.g/

> +. `Helped-by:` is used to credit someone with helping develop a
> +  patch.
> +. `Mentored-by:` is used to credit someone with helping develop a
> +  patch.

I think we use "Montored-by:" specifically to credit the mentor on 
patches written by GSoC or Outreachy interns and "Helped-by:" for the 
general case of someone helping the patch author.

> +. `Suggested-by:` is used to credit someone with suggesting the idea
> +  for a patch.
>   
>   You can also create your own tag or use one that's in common usage
> -such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
> +such as "Thanks-to:", "Based-on-patch-by:", or "Improved-by:".

What's the difference between "Improved-by:" and "Helped-by:"? In 
general I'd prefer for us not to encourage new trailers where we already 
have a suitable one in use.

Thanks for working on this, it will be good to have better descriptions 
of our common trailers.

Best Wishes

Phillip

Re: [PATCH 7/8] SubmittingPatches: clarify GitHub artifact format

[Elijah Newren]

On Tue, Dec 19, 2023 at 12:42 AM Josh Soref via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: Josh Soref <jsoref@gmail.com>
>
> GitHub wraps artifacts generated by workflows in a .zip file.
>
> Internally workflows can package anything they like in them.

s/Internally/Internal/?

>
> A recently generated failure artifact had the form:
>
> windows-artifacts.zip
>   Length      Date    Time    Name
> ---------  ---------- -----   ----
>  76001695  12-19-2023 01:35   artifacts.tar.gz
>  11005650  12-19-2023 01:35   tracked.tar.gz
> ---------                     -------
>  87007345                     2 files
>
> Signed-off-by: Josh Soref <jsoref@gmail.com>
> ---
>  Documentation/SubmittingPatches | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 8e19c7f82e4..b4fa52ae348 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -606,7 +606,8 @@ branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/ma
>  If a branch did not pass all test cases then it is marked with a red
>  +x+. In that case you can click on the failing job and navigate to
>  "ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You
> -can also download "Artifacts" which are tarred (or zipped) archives
> +can also download "Artifacts" which are zip archives containing
> +tarred (or zipped) archives
>  with test data relevant for debugging.
>
>  Then fix the problem and push your fix to your GitHub fork. This will
> --
> gitgitgadget
>

Re: [PATCH 4/8] SubmittingPatches: update extra tags list

[Elijah Newren]

To add to what Phillip said...

On Wed, Dec 20, 2023 at 7:18 AM Phillip Wood <phillip.wood123@gmail.com> wrote:
>
> Hi Josh
>
> On 19/12/2023 08:41, Josh Soref via GitGitGadget wrote:
> > From: Josh Soref <jsoref@gmail.com>
> >
> > Add items with at least 100 uses:
> > - Co-authored-by
> > - Helped-by
> > - Mentored-by
> > - Suggested-by
>
> Thanks for adding these, they are widely used and should be documented.
> The patch also adds a mention for "Noticed-by:" - I'm less convinced by
> the need for that as I explain below.
>
> > Updating the create suggestion to something less commonly used.
>
> I'm not quite sure I understand what you mean by this sentence.

Same.

> > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> > index 32e90238777..694a7bafb68 100644
> > --- a/Documentation/SubmittingPatches
> > +++ b/Documentation/SubmittingPatches
> > @@ -348,6 +348,8 @@ If you like, you can put extra tags at the end:
> >
> >   . `Reported-by:` is used to credit someone who found the bug that
> >     the patch attempts to fix.
> > +. `Noticed-by:` liked `Reported-by:` indicates someone who noticed
> > +  the item being fixed.
>
> I wonder if we really need a separate "Noticed-by" footer in addition to
> "Reported-by". Personally I use the latter to acknowledge the person who
> reported the issue being fix regards of weather I'm fixing a bug or some
> other issue.

I'm not sure I'd mention both either; feels like we're making it hard
for users to choose.  Also, I think there's a minor distinction
between them, but it's hard to convey simply: To me, Reported-by
suggests someone sent a mail to the list specifically about the bug or
issue in question.  Also, to me, Noticed-by suggests that during a
back-and-forth discussion of some sort on another topic, a fellow Git
contributor noticed an issue and mentioned it as an aside.  But,
that's how _I_ would have used them, I didn't do any digging to find
out if that's really how they are used.

Either way, if we're going to define them as synonyms, I'd rather we
just left the less common one out.  If there's a distinction, and it's
not a pain to describe, then maybe it'd be worth adding both.

If we do add both, though, we at least need to fix "liked" to "like"
in your description.

> >   . `Acked-by:` says that the person who is more familiar with the area
> >     the patch attempts to modify liked the patch.
> >   . `Reviewed-by:`, unlike the other tags, can only be offered by the
> > @@ -355,9 +357,17 @@ If you like, you can put extra tags at the end:
> >     patch after a detailed analysis.
> >   . `Tested-by:` is used to indicate that the person applied the patch
> >     and found it to have the desired effect.
> > +. `Co-authored-by:` is used to indicate that multiple people
> > +  contributed to the work of a patch.
>
> Junio's comments in [1] may be helpful here
>
>      If co-authors closely worked together (possibly but not necessarily
>      outside the public view), exchanging drafts and agreeing on the
>      final version before sending it to the list, by one approving the
>      other's final draft, Co-authored-by may be appropriate.
>
>      I would prefer to see more use of Helped-by when suggestions for
>      improvements were made, possibly but not necessarily in a concrete
>      "squashable patch" form, the original author accepted before
>      sending the new version out, and the party who made suggestions saw
>      the updated version at the same time as the general public.
>
> So I think we should be clear that "Co-authored-by:" means that multiple
> authors worked closely together on the patch, rather than just
> contributed to it.
>
> [1] https://lore.kernel.org/git/xmqqmth8wwcf.fsf@gitster.g/
>
> > +. `Helped-by:` is used to credit someone with helping develop a
> > +  patch.
> > +. `Mentored-by:` is used to credit someone with helping develop a
> > +  patch.
>
> I think we use "Montored-by:" specifically to credit the mentor on
> patches written by GSoC or Outreachy interns and "Helped-by:" for the
> general case of someone helping the patch author.

Yes; I'd like for these to be distinguished in this way or something similar.

> > +. `Suggested-by:` is used to credit someone with suggesting the idea
> > +  for a patch.
> >
> >   You can also create your own tag or use one that's in common usage
> > -such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
> > +such as "Thanks-to:", "Based-on-patch-by:", or "Improved-by:".
>
> What's the difference between "Improved-by:" and "Helped-by:"? In
> general I'd prefer for us not to encourage new trailers where we already
> have a suitable one in use.

Agreed.

> Thanks for working on this, it will be good to have better descriptions
> of our common trailers.

Agreed here as well; thanks for the work, Josh.

Re: [PATCH 6/8] SubmittingPatches: clarify GitHub visual

[Elijah Newren]

On Tue, Dec 19, 2023 at 6:44 AM René Scharfe <l.s.r@web.de> wrote:
>
> Am 19.12.23 um 09:41 schrieb Josh Soref via GitGitGadget:
> > From: Josh Soref <jsoref@gmail.com>
> >
> > Some people would expect a cross to be upright, and potentially have
> > unequal lengths...
>
> There are lots of types of crosses.  And while looking them up on
> Wikipedia I learned today that an x-cross is called "saltire" in
> English.  I only knew it as St. Andrew's cross before.
>
> > GitHub uses a white x overlaying a solid red circle to indicate failure.
>
> They call it "x-circle-fill"
> (https://primer.github.io/octicons/x-circle-fill-16).
>
> >
> > Signed-off-by: Josh Soref <jsoref@gmail.com>
> > ---
> >  Documentation/SubmittingPatches | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> >
> > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> > index d7a84f59478..8e19c7f82e4 100644
> > --- a/Documentation/SubmittingPatches
> > +++ b/Documentation/SubmittingPatches
> > @@ -604,7 +604,7 @@ to your fork of Git on GitHub.  You can monitor the test state of all your
> >  branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml`
> >
> >  If a branch did not pass all test cases then it is marked with a red
> > -cross. In that case you can click on the failing job and navigate to
> > ++x+. In that case you can click on the failing job and navigate to
>
> In the commit message you say the x is white, here it's red, so what is
> it?  IIUC the circle is red and the x-cross inside is the same color as
> the background, i.e. white in light mode and black in dark mode.  No
> idea how to express that in one word.  Perhaps "red circle containing
> and x-cross"?

There's an "and" vs "an" typo there, I think.  I'm tempted to just
oversimplify ("...marked with red."), but am slightly concerned about
red/green color-blind folks.  I suspect they'd figure it out anyway by
comparing the checkmarks (within green) to the x's (within red), but
if we want to be more detailed, perhaps we drop the "cross" altogether
and just describe it literally: "...marked with a red circle
containing a white x."?

Re: [PATCH 0/8] Minor improvements to CodingGuidelines and SubmittingPatches

[Elijah Newren]

On Tue, Dec 19, 2023 at 12:42 AM Josh Soref via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> These are a bunch of things I've run into over my past couple of attempts to
> contribute to Git.
>
>  * Incremental punctuation/grammatical improvements
>  * Update extra tags suggestions based on common usage
>  * drop reference to an article that was discontinued over a decade ago
>  * update GitHub references
>  * harmonize non-ASCII while I'm here

I commented on patches 4, 6, and 7 suggesting some changes.  Patch 1
is "meh" to me, but it doesn't hurt anything.  The other four all look
like good cleanups to me.

Re: [PATCH 4/8] SubmittingPatches: update extra tags list

[Josh Soref]

On Wed, Dec 20, 2023 at 10:30 AM Elijah Newren <newren@gmail.com> wrote:
> On Wed, Dec 20, 2023 at 7:18 AM Phillip Wood <phillip.wood123@gmail.com> wrote:
> > Thanks for adding these, they are widely used and should be documented.
> > The patch also adds a mention for "Noticed-by:" - I'm less convinced by
> > the need for that as I explain below.
> >
> > > Updating the create suggestion to something less commonly used.
> >
> > I'm not quite sure I understand what you mean by this sentence.

Tentatively rewritten as:
    Updating the "create your own tag" suggestion as 'Mentored-by' has been
    promoted.

This commit is adding bulleted items including promoting 'Mentored-by',
which means that the suggestion of "invent your own" would really need
a new suggestion.

Personally I'm not a fan of "invent your own", but I'm trying to
follow "when in Rome" (which is a big thing in the Git process
documentation covered by the two files subject to this series). More
on this later.

> > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> > > index 32e90238777..694a7bafb68 100644
> > > @@ -348,6 +348,8 @@ If you like, you can put extra tags at the end:
> > >
> > >   . `Reported-by:` is used to credit someone who found the bug that
> > >     the patch attempts to fix.
> > > +. `Noticed-by:` liked `Reported-by:` indicates someone who noticed
> > > +  the item being fixed.
> >
> > I wonder if we really need a separate "Noticed-by" footer in addition to
> > "Reported-by". Personally I use the latter to acknowledge the person who
> > reported the issue being fix regards of weather I'm fixing a bug or some
> > other issue.
>
> I'm not sure I'd mention both either; feels like we're making it hard
> for users to choose.  Also, I think there's a minor distinction
> between them, but it's hard to convey simply: To me, Reported-by
> suggests someone sent a mail to the list specifically about the bug or
> issue in question.  Also, to me, Noticed-by suggests that during a
> back-and-forth discussion of some sort on another topic, a fellow Git
> contributor noticed an issue and mentioned it as an aside.  But,
> that's how _I_ would have used them, I didn't do any digging to find
> out if that's really how they are used.

Given that Noticed-by is more common than Co-authored-by, I have a
hard time arguing that it shouldn't be included.
You could see that I struggled with it based on my lousy first drafts [1].

Anyway, tentatively:

. `Noticed-by:` like `Reported-by:` indicates a Git contributor who
called the item (being fixed) out as an aside.

Here, I'm struggling with the tension between "noticed-by probably
hints that something is being fixed" and "noticed-by is addressing who
suggested it and why we're attributing it to them"

"as an aside" is itself an ellipsis for something like "as an aside to
some unrelated discussion and didn't really circle back to it as a top
level discussion point, but here we're closing the loop" -- but this
is obviously way too long-winded to be the written form.

> Either way, if we're going to define them as synonyms, I'd rather we
> just left the less common one out.  If there's a distinction, and it's
> not a pain to describe, then maybe it'd be worth adding both.
>
> If we do add both, though, we at least need to fix "liked" to "like"
> in your description.

Right, it's a "first draft" [1]...

> > > +. `Co-authored-by:` is used to indicate that multiple people
> > > +  contributed to the work of a patch.
> >
> > Junio's comments in [1] may be helpful here
> >
> >      If co-authors closely worked together (possibly but not necessarily
> >      outside the public view), exchanging drafts and agreeing on the
> >      final version before sending it to the list, by one approving the
> >      other's final draft, Co-authored-by may be appropriate.
> >
> >      I would prefer to see more use of Helped-by when suggestions for
> >      improvements were made, possibly but not necessarily in a concrete
> >      "squashable patch" form, the original author accepted before
> >      sending the new version out, and the party who made suggestions saw
> >      the updated version at the same time as the general public.
> >
> > So I think we should be clear that "Co-authored-by:" means that multiple
> > authors worked closely together on the patch, rather than just
> > contributed to it.

Tentatively:
. `Co-authored-by:` is used to indicate that people exchanged drafts
of a patch before submitting it.

Note that I'm dropping `multiple` -- people implies that.

. `Helped-by:` is used to credit someone who suggested ideas for
changes without providing the precise changes in patch form.

> > I think we use "Montored-by:" specifically to credit the mentor on
> > patches written by GSoC or Outreachy interns and "Helped-by:" for the
> > general case of someone helping the patch author.
>
> Yes; I'd like for these to be distinguished in this way or something similar.

. `Mentored-by:` is used to credit someone with helping develop a
patch as part of a mentorship program (e.g., GSoC or Outreachy).

> > >   You can also create your own tag or use one that's in common usage
> > > -such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
> > > +such as "Thanks-to:", "Based-on-patch-by:", or "Improved-by:".
> >
> > What's the difference between "Improved-by:" and "Helped-by:"?

I dunno. This entire section (as I called out at the beginning) is
frustrating...

Anyway, see all of us struggle with it below:

> > In
> > general I'd prefer for us not to encourage new trailers where we already
> > have a suitable one in use.

If this text needs to survive without being drastically changed, it
needs a warning saying "don't create a new tag if there's an already
used tag that seems like it'll cover what you're trying to say --
here's how to review them...". Note that I'd argue the cost being
asked of someone to do this research far exceeds what is reasonable to
ask of a new contributor, which is why I'd rather say that new
contributors shouldn't be inventing tags.

> Agreed.

I personally agree. I think encouraging non-core contributors to
invent their own is not a good idea. It leads to various things
(including inconsistently cased items because users fail to review the
current set / understand them/their-construction).

Saying that it's ok for core contributors to suggest a new tag and
that if a core contributor suggests a new tag that the person writing
the current series should just accept the tag and trust that it'll be
ok.

Note: I'm not going to draft wording to this effect on my own, and if
I were to provide such a change, it'd be its own commit prior to the
one here, because it's a significant process change as opposed to
clarifying the list of recommended tags.

> > Thanks for working on this, it will be good to have better descriptions
> > of our common trailers.
>
> Agreed here as well; thanks for the work, Josh.

[1] The Late Show With Stephen Colbert has a running segment called
First Drafts which showcases lousy first drafts of greeting cards,
they've https://www.cbsstore.com/products/the-late-show-with-stephen-colbert-first-drafts-greeting-card-pack-sc1193

Re: [PATCH 7/8] SubmittingPatches: clarify GitHub artifact format

[Josh Soref]

Elijah Newren <newren@gmail.com> wrote:
> > From: Josh Soref <jsoref@gmail.com>
> >
> > GitHub wraps artifacts generated by workflows in a .zip file.
> >
> > Internally workflows can package anything they like in them.
>
> s/Internally/Internal/?

No, it's actually:

s/Internally/Internally,/

In that, what a workflow does to structure the contents of a .zip
artifact is an implementation decision of the workflow.

Re: [PATCH 6/8] SubmittingPatches: clarify GitHub visual

[Josh Soref]

Elijah Newren <newren@gmail.com> wrote:
> On Tue, Dec 19, 2023 at 6:44 AM René Scharfe <l.s.r@web.de> wrote:
> > Am 19.12.23 um 09:41 schrieb Josh Soref via GitGitGadget:
> > > From: Josh Soref <jsoref@gmail.com>
> > > Some people would expect a cross to be upright, and potentially have
> > > unequal lengths...
> > There are lots of types of crosses.  And while looking them up on
> > Wikipedia I learned today that an x-cross is called "saltire" in
> > English.  I only knew it as St. Andrew's cross before.
> >
> > > GitHub uses a white x overlaying a solid red circle to indicate failure.
> >
> > They call it "x-circle-fill"
> > (https://primer.github.io/octicons/x-circle-fill-16).

> > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> > > @@ -604,7 +604,7 @@ to your fork of Git on GitHub.  You can monitor the test state of all your
> > >  branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml`
> > >
> > >  If a branch did not pass all test cases then it is marked with a red
> > > -cross. In that case you can click on the failing job and navigate to
> > > ++x+. In that case you can click on the failing job and navigate to
> >
> > In the commit message you say the x is white, here it's red, so what is
> > it?  IIUC the circle is red and the x-cross inside is the same color as
> > the background, i.e. white in light mode and black in dark mode.  No
> > idea how to express that in one word.  Perhaps "red circle containing
> > and x-cross"?

This was an oversimplification, which I deeply regret.

It uses a simple red x (❌) in some views, e.g.:
https://github.com/gitgitgadget/git/pull/1620

And in other views it uses a red circle with what's actually a
transparent x (white at the top if using light mode, gray fill if you
select linux-leaks on the left, and dark gray fill in the log view):
https://github.com/gitgitgadget/git/actions/runs/7265353611/job/19794849212?pr=1620

> There's an "and" vs "an" typo there, I think.  I'm tempted to just
> oversimplify ("...marked with red."), but am slightly concerned about
> red/green color-blind folks.  I suspect they'd figure it out anyway by
> comparing the checkmarks (within green) to the x's (within red), but
> if we want to be more detailed, perhaps we drop the "cross" altogether
> and just describe it literally: "...marked with a red circle
> containing a white x."?

Your text aligns with what I drafted as a response but didn't send:

I think it's simplest to say an `x`, or maybe "red color and an x".

Re: [PATCH 4/8] SubmittingPatches: update extra tags list

[Junio C Hamano]

Phillip Wood <phillip.wood123@gmail.com> writes:

> What's the difference between "Improved-by:" and "Helped-by:"? In
> general I'd prefer for us not to encourage new trailers where we
> already have a suitable one in use.

I agree with the direction to limit the trailer tokens to common
ones, as the repertoire we have sufficiently covers the needs
already, and strongly discourage folks to waste their time trying to
be "original".

It might be useful to run stats of trailers that were used in the
past, say, 3 years and that may give us a good guide to decide which
ones to limit ourselves to.

Thanks for reviewing.

Re: [PATCH 6/8] SubmittingPatches: clarify GitHub visual

[Junio C Hamano]

Elijah Newren <newren@gmail.com> writes:

> ...  I'm tempted to just
> oversimplify ("...marked with red."), but am slightly concerned about
> red/green color-blind folks.

(sheepishly raises hand).  Thanks for being considerate.

> I suspect they'd figure it out anyway by
> comparing the checkmarks (within green) to the x's (within red),

I 100% agree with this.

> but
> if we want to be more detailed, perhaps we drop the "cross" altogether
> and just describe it literally: "...marked with a red circle
> containing a white x."?

Thanks.

Re: [PATCH 4/8] SubmittingPatches: update extra tags list

[Elijah Newren]

On Wed, Dec 20, 2023 at 8:09 AM Josh Soref <jsoref@gmail.com> wrote:
>
> On Wed, Dec 20, 2023 at 10:30 AM Elijah Newren <newren@gmail.com> wrote:
> > On Wed, Dec 20, 2023 at 7:18 AM Phillip Wood <phillip.wood123@gmail.com> wrote:
> > > Thanks for adding these, they are widely used and should be documented.
> > > The patch also adds a mention for "Noticed-by:" - I'm less convinced by
> > > the need for that as I explain below.
> > >
> > > > Updating the create suggestion to something less commonly used.
> > >
> > > I'm not quite sure I understand what you mean by this sentence.
>
> Tentatively rewritten as:
>     Updating the "create your own tag" suggestion as 'Mentored-by' has been
>     promoted.
>
> This commit is adding bulleted items including promoting 'Mentored-by',
> which means that the suggestion of "invent your own" would really need
> a new suggestion.
>
> Personally I'm not a fan of "invent your own", but I'm trying to
> follow "when in Rome" (which is a big thing in the Git process
> documentation covered by the two files subject to this series). More
> on this later.

Yeah, well it appears that those of us who have been here in Rome for
a while aren't a fan of it anymore either; see also Junio's response
in this thread about that.

> > > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> > > > index 32e90238777..694a7bafb68 100644
> > > > @@ -348,6 +348,8 @@ If you like, you can put extra tags at the end:
> > > >
> > > >   . `Reported-by:` is used to credit someone who found the bug that
> > > >     the patch attempts to fix.
> > > > +. `Noticed-by:` liked `Reported-by:` indicates someone who noticed
> > > > +  the item being fixed.
> > >
> > > I wonder if we really need a separate "Noticed-by" footer in addition to
> > > "Reported-by". Personally I use the latter to acknowledge the person who
> > > reported the issue being fix regards of weather I'm fixing a bug or some
> > > other issue.
> >
> > I'm not sure I'd mention both either; feels like we're making it hard
> > for users to choose.  Also, I think there's a minor distinction
> > between them, but it's hard to convey simply: To me, Reported-by
> > suggests someone sent a mail to the list specifically about the bug or
> > issue in question.  Also, to me, Noticed-by suggests that during a
> > back-and-forth discussion of some sort on another topic, a fellow Git
> > contributor noticed an issue and mentioned it as an aside.  But,
> > that's how _I_ would have used them, I didn't do any digging to find
> > out if that's really how they are used.
>
> Given that Noticed-by is more common than Co-authored-by, I have a
> hard time arguing that it shouldn't be included.

Not if you look at the last three years; there Co-authored-by is more
than 17 times more common than Noticed-by.

> You could see that I struggled with it based on my lousy first drafts [1].
>
> Anyway, tentatively:
>
> . `Noticed-by:` like `Reported-by:` indicates a Git contributor who
> called the item (being fixed) out as an aside.
>
> Here, I'm struggling with the tension between "noticed-by probably
> hints that something is being fixed" and "noticed-by is addressing who
> suggested it and why we're attributing it to them"
>
> "as an aside" is itself an ellipsis for something like "as an aside to
> some unrelated discussion and didn't really circle back to it as a top
> level discussion point, but here we're closing the loop" -- but this
> is obviously way too long-winded to be the written form

Given the large drop-off in usage of the Noticed-by trailer, I'd
suggest just leaving it out.

> > Either way, if we're going to define them as synonyms, I'd rather we
> > just left the less common one out.  If there's a distinction, and it's
> > not a pain to describe, then maybe it'd be worth adding both.
> >
> > If we do add both, though, we at least need to fix "liked" to "like"
> > in your description.
>
> Right, it's a "first draft" [1]...

:-)

[...]

> I personally agree. I think encouraging non-core contributors to
> invent their own is not a good idea. It leads to various things
> (including inconsistently cased items because users fail to review the
> current set / understand them/their-construction).
>
> Saying that it's ok for core contributors to suggest a new tag and
> that if a core contributor suggests a new tag that the person writing
> the current series should just accept the tag and trust that it'll be
> ok.
>
> Note: I'm not going to draft wording to this effect on my own, and if
> I were to provide such a change, it'd be its own commit prior to the
> one here, because it's a significant process change as opposed to
> clarifying the list of recommended tags.

Perhaps replace

   You can also create your own tag or use one that's in common usage
   such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".

with

   While you can also create your own trailer if the situation warrants it, we
   encourage you to instead use one of the common trailers in this project
   highlighted above.

?

Re: [PATCH 7/8] SubmittingPatches: clarify GitHub artifact format

[Elijah Newren]

On Wed, Dec 20, 2023 at 8:16 AM Josh Soref <jsoref@gmail.com> wrote:
>
> Elijah Newren <newren@gmail.com> wrote:
> > > From: Josh Soref <jsoref@gmail.com>
> > >
> > > GitHub wraps artifacts generated by workflows in a .zip file.
> > >
> > > Internally workflows can package anything they like in them.
> >
> > s/Internally/Internal/?
>
> No, it's actually:
>
> s/Internally/Internally,/
>
> In that, what a workflow does to structure the contents of a .zip
> artifact is an implementation decision of the workflow.

Ah, that makes sense with the comma; thanks.

Re: [PATCH 4/8] SubmittingPatches: update extra tags list

[Josh Soref]

Elijah Newren wrote:
> Yeah, well it appears that those of us who have been here in Rome for
> a while aren't a fan of it anymore either; see also Junio's response
> in this thread about that.

Right.

> [Josh Soref <jsoref@gmail.com> wrote:]
> > Given that Noticed-by is more common than Co-authored-by, I have a
> > hard time arguing that it shouldn't be included.
>
> Not if you look at the last three years; there Co-authored-by is more
> than 17 times more common than Noticed-by.

> Given the large drop-off in usage of the Noticed-by trailer, I'd
> suggest just leaving it out.



> Perhaps replace
>
>    You can also create your own tag or use one that's in common usage
>    such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
>
> with
>
>    While you can also create your own trailer if the situation warrants it, we
>    encourage you to instead use one of the common trailers in this project
>    highlighted above.
>
> ?

Let's have some fun (inception):

commit eac2211332f754c5f4127a58aafb9882bfe939e8
Author: Josh Soref <jsoref@gmail.com>
Date:   Wed Dec 20 12:34:54 2023 -0500

    SubmittingPatches: discourage new trailers

    There seems to be consensus amongst the core Git community on a working
    set of common trailers, and there are non-trivial costs to people
    inventing new trailers (research to discover what they mean/how they
    differ from existing trailers) such that inventing new ones is generally
    unwarranted and not something to be recommended to new contributors.

    Suggested-by: Elijah Newren <newren@gmail.com>
    Signed-off-by: Josh Soref <jsoref@gmail.com>

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 32e9023877..58dfe40504 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -358,4 +358,5 @@ If you like, you can put extra tags at the end:

-You can also create your own tag or use one that's in common usage
-such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
+While you can also create your own trailer if the situation warrants it, we
+encourage you to instead use one of the common trailers in this project
+highlighted above.

Re: [PATCH 4/8] SubmittingPatches: update extra tags list

[phillip.wood123]

Hi Josh

On 20/12/2023 17:42, Josh Soref wrote:
>      SubmittingPatches: discourage new trailers
> 
>      There seems to be consensus amongst the core Git community on a working
>      set of common trailers, and there are non-trivial costs to people
>      inventing new trailers (research to discover what they mean/how they
>      differ from existing trailers) such that inventing new ones is generally
>      unwarranted and not something to be recommended to new contributors.
> 
>      Suggested-by: Elijah Newren <newren@gmail.com>
>      Signed-off-by: Josh Soref <jsoref@gmail.com>
> 
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 32e9023877..58dfe40504 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -358,4 +358,5 @@ If you like, you can put extra tags at the end:
> 
> -You can also create your own tag or use one that's in common usage
> -such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
> +While you can also create your own trailer if the situation warrants it, we
> +encourage you to instead use one of the common trailers in this project
> +highlighted above.

Thanks for this, it looks good and would be a useful addition to v2 of 
your patch series.

Best Wishes

Phillip

[PATCH v2 0/9] Minor improvements to CodingGuidelines and SubmittingPatches

[Josh Soref via GitGitGadget]

These are a bunch of things I've run into over my past couple of attempts to
contribute to Git.

 * Incremental punctuation/grammatical improvements
 * Update extra tags suggestions based on common usage
 * drop reference to an article that was discontinued over a decade ago
 * update GitHub references
 * harmonize non-ASCII while I'm here

Note that I'm trying to do things "in the neighborhood". It'll be slower
than me replacing things topically, but hopefully easier for others to
digest. My current estimate is a decade or two :).

Josh Soref (9):
  CodingGuidelines: move period inside parentheses
  CodingGuidelines: write punctuation marks
  SubmittingPatches: drop ref to "What's in git.git"
  SubmittingPatches: discourage new trailers
  SubmittingPatches: update extra tags list
  SubmittingPatches: improve extra tags advice
  SubmittingPatches: clarify GitHub visual
  SubmittingPatches: clarify GitHub artifact format
  SubmittingPatches: hyphenate non-ASCII

 Documentation/CodingGuidelines  |  4 ++--
 Documentation/SubmittingPatches | 27 ++++++++++++++++++++-------
 2 files changed, 22 insertions(+), 9 deletions(-)


base-commit: 624eb90fa8f65a79396615f3c2842ac5a3743350
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1623%2Fjsoref%2Fdocumentation-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1623/jsoref/documentation-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1623

Range-diff vs v1:

  1:  b9a8eb6aa4e =  1:  b9a8eb6aa4e CodingGuidelines: move period inside parentheses
  2:  c0db8336e51 =  2:  c0db8336e51 CodingGuidelines: write punctuation marks
  3:  22d66c5b78a =  3:  22d66c5b78a SubmittingPatches: drop ref to "What's in git.git"
  4:  e5c7f29af43 !  4:  eac2211332f SubmittingPatches: update extra tags list
     @@ Metadata
      Author: Josh Soref <jsoref@gmail.com>
      
       ## Commit message ##
     -    SubmittingPatches: update extra tags list
     +    SubmittingPatches: discourage new trailers
      
     -    Add items with at least 100 uses:
     -    - Co-authored-by
     -    - Helped-by
     -    - Mentored-by
     -    - Suggested-by
     -
     -    Updating the create suggestion to something less commonly used.
     -
     -    git log |
     -      perl -ne 'next unless /^\s+[A-Z][a-z]+-\S+:/;s/^\s+//;s/:.*/:/;print'|
     -      sort|uniq -c|sort -n|grep '[0-9][0-9] '
     -      11 Helped-By:
     -      13 Message-ID:
     -      14 Reported-By:
     -      22 Acked-By:
     -      27 Inspired-by:
     -      29 Requested-by:
     -      35 Original-patch-by:
     -      43 Contributions-by:
     -      47 Signed-Off-By:
     -      65 Based-on-patch-by:
     -      68 Thanks-to:
     -      88 Improved-by:
     -     145 Co-authored-by:
     -     171 Noticed-by:
     -     182 Tested-by:
     -     361 Suggested-by:
     -     469 Mentored-by:
     -    1196 Reported-by:
     -    1727 Helped-by:
     -    2177 Reviewed-by:
     -    2202 Acked-by:
     -    95313 Signed-off-by:
     +    There seems to be consensus amongst the core Git community on a working
     +    set of common trailers, and there are non-trivial costs to people
     +    inventing new trailers (research to discover what they mean/how they
     +    differ from existing trailers) such that inventing new ones is generally
     +    unwarranted and not something to be recommended to new contributors.
      
     +    Suggested-by: Elijah Newren <newren@gmail.com>
          Signed-off-by: Josh Soref <jsoref@gmail.com>
      
       ## Documentation/SubmittingPatches ##
      @@ Documentation/SubmittingPatches: If you like, you can put extra tags at the end:
     - 
     - . `Reported-by:` is used to credit someone who found the bug that
     -   the patch attempts to fix.
     -+. `Noticed-by:` liked `Reported-by:` indicates someone who noticed
     -+  the item being fixed.
     - . `Acked-by:` says that the person who is more familiar with the area
     -   the patch attempts to modify liked the patch.
     - . `Reviewed-by:`, unlike the other tags, can only be offered by the
     -@@ Documentation/SubmittingPatches: If you like, you can put extra tags at the end:
     -   patch after a detailed analysis.
       . `Tested-by:` is used to indicate that the person applied the patch
         and found it to have the desired effect.
     -+. `Co-authored-by:` is used to indicate that multiple people
     -+  contributed to the work of a patch.
     -+. `Helped-by:` is used to credit someone with helping develop a
     -+  patch.
     -+. `Mentored-by:` is used to credit someone with helping develop a
     -+  patch.
     -+. `Suggested-by:` is used to credit someone with suggesting the idea
     -+  for a patch.
       
     - You can also create your own tag or use one that's in common usage
     +-You can also create your own tag or use one that's in common usage
      -such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
     -+such as "Thanks-to:", "Based-on-patch-by:", or "Improved-by:".
     ++While you can also create your own trailer if the situation warrants it, we
     ++encourage you to instead use one of the common trailers in this project
     ++highlighted above.
       
       [[git-tools]]
       === Generate your patch using Git tools out of your commits.
  -:  ----------- >  5:  8848572fe2c SubmittingPatches: update extra tags list
  5:  11688e4360c !  6:  8f16c7caa73 SubmittingPatches: improve extra tags advice
     @@ Commit message
          Signed-off-by: Josh Soref <jsoref@gmail.com>
      
       ## Documentation/SubmittingPatches ##
     -@@ Documentation/SubmittingPatches: If you like, you can put extra tags at the end:
     - You can also create your own tag or use one that's in common usage
     - such as "Thanks-to:", "Based-on-patch-by:", or "Improved-by:".
     +@@ Documentation/SubmittingPatches: While you can also create your own trailer if the situation warrants it, we
     + encourage you to instead use one of the common trailers in this project
     + highlighted above.
       
      +Extra tags should only capitalize the very first letter, i.e. favor
      +"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By".
  6:  043d2a24202 !  7:  cdb5fd0957f SubmittingPatches: clarify GitHub visual
     @@ Metadata
       ## Commit message ##
          SubmittingPatches: clarify GitHub visual
      
     -    Some people would expect a cross to be upright, and potentially have
     -    unequal lengths...
     +    GitHub has two general forms for its states, sometimes they're a simple
     +    colored object (e.g. green check or red x), and sometimes there's also a
     +    colored container (e.g. green box or red circle) with containing that
     +    object (e.g. check or x).
      
     -    GitHub uses a white x overlaying a solid red circle to indicate failure.
     +    That's a lot of words to try to describe things, but in general, the key
     +    for a failure is that it's recognized as an `x` and that it's associated
     +    with the color red -- the color of course is problematic for people who
     +    are red-green color-blind, but that's why they are paired with distinct
     +    shapes.
     +
     +    Using the term `cross` doesn't really help.
      
          Signed-off-by: Josh Soref <jsoref@gmail.com>
      
  7:  cdab65a4259 !  8:  77576327df8 SubmittingPatches: clarify GitHub artifact format
     @@ Commit message
      
          GitHub wraps artifacts generated by workflows in a .zip file.
      
     -    Internally workflows can package anything they like in them.
     +    Internally, workflows can package anything they like in them.
      
          A recently generated failure artifact had the form:
      
  8:  92469324813 =  9:  a4878f58fe4 SubmittingPatches: hyphenate non-ASCII

-- 
gitgitgadget

[PATCH v2 1/9] CodingGuidelines: move period inside parentheses

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

The contents within parenthesis should be omittable without resulting
in broken text.

Eliding the parenthesis left a period to end a run without any content.

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/CodingGuidelines | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 8ed517a5ca0..af94ed3a75d 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -450,7 +450,7 @@ For C programs:
    one of the approved headers that includes it first for you.  (The
    approved headers currently include "builtin.h",
    "t/helper/test-tool.h", "xdiff/xinclude.h", or
-   "reftable/system.h").  You do not have to include more than one of
+   "reftable/system.h".)  You do not have to include more than one of
    these.
 
  - A C file must directly include the header files that declare the
-- 
gitgitgadget

[PATCH v2 2/9] CodingGuidelines: write punctuation marks

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

- Match style in Release Notes

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/CodingGuidelines | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index af94ed3a75d..578587a4715 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -578,7 +578,7 @@ Externally Visible Names
    . The variable name describes the effect of tweaking this knob.
 
    The section and variable names that consist of multiple words are
-   formed by concatenating the words without punctuations (e.g. `-`),
+   formed by concatenating the words without punctuation marks (e.g. `-`),
    and are broken using bumpyCaps in documentation as a hint to the
    reader.
 
-- 
gitgitgadget

[PATCH v2 3/9] SubmittingPatches: drop ref to "What's in git.git"

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

"What's in git.git" was last seen in 2010:
  https://lore.kernel.org/git/?q=%22what%27s+in+git.git%22
  https://lore.kernel.org/git/7vaavikg72.fsf@alter.siamese.dyndns.org/

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index bce7f97815c..32e90238777 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -570,7 +570,7 @@ their trees themselves.
   master).
 
 * Read the Git mailing list, the maintainer regularly posts messages
-  entitled "What's cooking in git.git" and "What's in git.git" giving
+  entitled "What's cooking in git.git" giving
   the status of various proposed changes.
 
 == GitHub CI[[GHCI]]
-- 
gitgitgadget

[PATCH v2 4/9] SubmittingPatches: discourage new trailers

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

There seems to be consensus amongst the core Git community on a working
set of common trailers, and there are non-trivial costs to people
inventing new trailers (research to discover what they mean/how they
differ from existing trailers) such that inventing new ones is generally
unwarranted and not something to be recommended to new contributors.

Suggested-by: Elijah Newren <newren@gmail.com>
Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 32e90238777..58dfe405049 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -356,8 +356,9 @@ If you like, you can put extra tags at the end:
 . `Tested-by:` is used to indicate that the person applied the patch
   and found it to have the desired effect.
 
-You can also create your own tag or use one that's in common usage
-such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
+While you can also create your own trailer if the situation warrants it, we
+encourage you to instead use one of the common trailers in this project
+highlighted above.
 
 [[git-tools]]
 === Generate your patch using Git tools out of your commits.
-- 
gitgitgadget

[PATCH v2 5/9] SubmittingPatches: update extra tags list

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

Add items with at least 100 uses in the past three years:
- Co-authored-by
- Helped-by
- Mentored-by
- Suggested-by

git log --since=3.years|
  perl -ne 'next unless /^\s+[A-Z][a-z]+-\S+:/;s/^\s+//;s/:.*/:/;print'|
  sort|uniq -c|sort -n|grep '[0-9][0-9] '
  14 Based-on-patch-by:
  14 Original-patch-by:
  17 Tested-by:
 100 Suggested-by:
 121 Co-authored-by:
 163 Mentored-by:
 274 Reported-by:
 290 Acked-by:
 450 Helped-by:
 602 Reviewed-by:
14111 Signed-off-by:

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 58dfe405049..31878cb70b7 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -355,6 +355,14 @@ If you like, you can put extra tags at the end:
   patch after a detailed analysis.
 . `Tested-by:` is used to indicate that the person applied the patch
   and found it to have the desired effect.
+. `Co-authored-by:` is used to indicate that people exchanged drafts
+   of a patch before submitting it.
+. `Helped-by:` is used to credit someone who suggested ideas for
+  changes without providing the precise changes in patch form.
+. `Mentored-by:` is used to credit someone with helping develop a
+  patch as part of a mentorship program (e.g., GSoC or Outreachy).
+. `Suggested-by:` is used to credit someone with suggesting the idea
+  for a patch.
 
 While you can also create your own trailer if the situation warrants it, we
 encourage you to instead use one of the common trailers in this project
-- 
gitgitgadget

[PATCH v2 6/9] SubmittingPatches: improve extra tags advice

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

Current statistics show a strong preference to only capitalize the first
letter in a hyphenated tag, but that some guidance would be helpful:

git log |
  perl -ne 'next unless /^\s+(?:Signed-[oO]ff|Acked)-[bB]y:/;
    s/^\s+//;s/:.*/:/;print'|
  sort|uniq -c|sort -n
   2 Signed-off-By:
   4 Signed-Off-by:
  22 Acked-By:
  47 Signed-Off-By:
2202 Acked-by:
95315 Signed-off-by:

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 31878cb70b7..4476b52a50f 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -368,6 +368,9 @@ While you can also create your own trailer if the situation warrants it, we
 encourage you to instead use one of the common trailers in this project
 highlighted above.
 
+Extra tags should only capitalize the very first letter, i.e. favor
+"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By".
+
 [[git-tools]]
 === Generate your patch using Git tools out of your commits.
 
-- 
gitgitgadget

[PATCH v2 7/9] SubmittingPatches: clarify GitHub visual

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

GitHub has two general forms for its states, sometimes they're a simple
colored object (e.g. green check or red x), and sometimes there's also a
colored container (e.g. green box or red circle) with containing that
object (e.g. check or x).

That's a lot of words to try to describe things, but in general, the key
for a failure is that it's recognized as an `x` and that it's associated
with the color red -- the color of course is problematic for people who
are red-green color-blind, but that's why they are paired with distinct
shapes.

Using the term `cross` doesn't really help.

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 4476b52a50f..8f79253c5cb 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -603,7 +603,7 @@ to your fork of Git on GitHub.  You can monitor the test state of all your
 branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml`
 
 If a branch did not pass all test cases then it is marked with a red
-cross. In that case you can click on the failing job and navigate to
++x+. In that case you can click on the failing job and navigate to
 "ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You
 can also download "Artifacts" which are tarred (or zipped) archives
 with test data relevant for debugging.
-- 
gitgitgadget

[PATCH v2 8/9] SubmittingPatches: clarify GitHub artifact format

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

GitHub wraps artifacts generated by workflows in a .zip file.

Internally, workflows can package anything they like in them.

A recently generated failure artifact had the form:

windows-artifacts.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
 76001695  12-19-2023 01:35   artifacts.tar.gz
 11005650  12-19-2023 01:35   tracked.tar.gz
---------                     -------
 87007345                     2 files

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 8f79253c5cb..cb0dcce6a17 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -605,7 +605,8 @@ branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/ma
 If a branch did not pass all test cases then it is marked with a red
 +x+. In that case you can click on the failing job and navigate to
 "ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You
-can also download "Artifacts" which are tarred (or zipped) archives
+can also download "Artifacts" which are zip archives containing
+tarred (or zipped) archives
 with test data relevant for debugging.
 
 Then fix the problem and push your fix to your GitHub fork. This will
-- 
gitgitgadget

[PATCH v2 9/9] SubmittingPatches: hyphenate non-ASCII

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

Git documentation does this with the exception of ancient release notes.

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index cb0dcce6a17..9283eb0ef71 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -699,7 +699,7 @@ message to an external program, and this is a handy way to drive
 `git am`.  However, if the message is MIME encoded, what is
 piped into the program is the representation you see in your
 `*Article*` buffer after unwrapping MIME.  This is often not what
-you would want for two reasons.  It tends to screw up non ASCII
+you would want for two reasons.  It tends to screw up non-ASCII
 characters (most notably in people's names), and also
 whitespaces (fatal in patches).  Running "C-u g" to display the
 message in raw form before using "|" to run the pipe can work
-- 
gitgitgadget

Re: [PATCH v2 2/9] CodingGuidelines: write punctuation marks

[Junio C Hamano]

"Josh Soref via GitGitGadget" <gitgitgadget@gmail.com> writes:

Nobody seems to have commented on this step in the previous round,
but I do not understand what you mean by ...

> From: Josh Soref <jsoref@gmail.com>
>
> - Match style in Release Notes

... at all.  The patch text is fine, though.

> Signed-off-by: Josh Soref <jsoref@gmail.com>
> ---
>  Documentation/CodingGuidelines | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> index af94ed3a75d..578587a4715 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -578,7 +578,7 @@ Externally Visible Names
>     . The variable name describes the effect of tweaking this knob.
>  
>     The section and variable names that consist of multiple words are
> -   formed by concatenating the words without punctuations (e.g. `-`),
> +   formed by concatenating the words without punctuation marks (e.g. `-`),
>     and are broken using bumpyCaps in documentation as a hint to the
>     reader.

Re: [PATCH v2 1/9] CodingGuidelines: move period inside parentheses

[Junio C Hamano]

"Josh Soref via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Josh Soref <jsoref@gmail.com>
>
> The contents within parenthesis should be omittable without resulting
> in broken text.
>
> Eliding the parenthesis left a period to end a run without any content.

Nobody seems to have commented on this one in the previous round,
but quite honestly, for this particular instance, I suspect that it
may become easier to read if we just lost these parentheses, as the
next sentence "You do not have to include more than ..." is just a
bit of extra material to support the first sentence like the one we
see in the parentheses.  Alternatively, moving that "You do not have
to" also inside the same parentheses might work slightly better.

It might be even easier to follow if we moved the list of "approved
headers" (and the "You do not have to ... more than one" note that
supports the "currently approved list") totally out of line by
making it a side note.

> Signed-off-by: Josh Soref <jsoref@gmail.com>
> ---
>  Documentation/CodingGuidelines | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> index 8ed517a5ca0..af94ed3a75d 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -450,7 +450,7 @@ For C programs:
>     one of the approved headers that includes it first for you.  (The
>     approved headers currently include "builtin.h",
>     "t/helper/test-tool.h", "xdiff/xinclude.h", or
> -   "reftable/system.h").  You do not have to include more than one of
> +   "reftable/system.h".)  You do not have to include more than one of
>     these.
>  
>   - A C file must directly include the header files that declare the

Re: [PATCH v2 3/9] SubmittingPatches: drop ref to "What's in git.git"

[Junio C Hamano]

"Josh Soref via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Josh Soref <jsoref@gmail.com>
>
> "What's in git.git" was last seen in 2010:
>   https://lore.kernel.org/git/?q=%22what%27s+in+git.git%22
>   https://lore.kernel.org/git/7vaavikg72.fsf@alter.siamese.dyndns.org/
>
> Signed-off-by: Josh Soref <jsoref@gmail.com>
> ---
>  Documentation/SubmittingPatches | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Thanks.  I stopped doing these long time ago, as there were certain
overlaps with "What's cooking" that lists the topics that have
graduated in a separate section.

>
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index bce7f97815c..32e90238777 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -570,7 +570,7 @@ their trees themselves.
>    master).
>  
>  * Read the Git mailing list, the maintainer regularly posts messages
> -  entitled "What's cooking in git.git" and "What's in git.git" giving
> +  entitled "What's cooking in git.git" giving
>    the status of various proposed changes.
>  
>  == GitHub CI[[GHCI]]

Re: [PATCH v2 5/9] SubmittingPatches: update extra tags list

[Junio C Hamano]

"Josh Soref via GitGitGadget" <gitgitgadget@gmail.com> writes:

> +. `Co-authored-by:` is used to indicate that people exchanged drafts
> +   of a patch before submitting it.

I am afraid this misses the essence of what Co-authoring means.
You may have shared your draft as FYI to your colleagues, and they
may have tweaked phrasing and responded with their reviews to help
you improve _your_ work, but that may not make them your Co-authors.

I think the "intent" counts more.  If people closely worked
together, exchanging drafts and agreeing on the final version among
themselves before submitting, with the understanding that they share
the authorship credit/blame, they are Co-authors.

> +. `Helped-by:` is used to credit someone who suggested ideas for
> +  changes without providing the precise changes in patch form.
> +. `Mentored-by:` is used to credit someone with helping develop a
> +  patch as part of a mentorship program (e.g., GSoC or Outreachy).

Nicely differentiated.

Re: [PATCH v2 6/9] SubmittingPatches: improve extra tags advice

[Junio C Hamano]

"Josh Soref via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Josh Soref <jsoref@gmail.com>
>
> Current statistics show a strong preference to only capitalize the first
> letter in a hyphenated tag, but that some guidance would be helpful:
>
> git log |
>   perl -ne 'next unless /^\s+(?:Signed-[oO]ff|Acked)-[bB]y:/;
>     s/^\s+//;s/:.*/:/;print'|
>   sort|uniq -c|sort -n
>    2 Signed-off-By:
>    4 Signed-Off-by:
>   22 Acked-By:
>   47 Signed-Off-By:
> 2202 Acked-by:
> 95315 Signed-off-by:
>
> Signed-off-by: Josh Soref <jsoref@gmail.com>
> ---
>  Documentation/SubmittingPatches | 3 +++
>  1 file changed, 3 insertions(+)
>
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 31878cb70b7..4476b52a50f 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -368,6 +368,9 @@ While you can also create your own trailer if the situation warrants it, we
>  encourage you to instead use one of the common trailers in this project
>  highlighted above.
>  
> +Extra tags should only capitalize the very first letter, i.e. favor
> +"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By".

Drop "Extra", perhaps?  The sentence before already discourages any
extra ones, and what this sentence teaches the contributors is to
avoud spelling variation when to spell the common ones.

>  [[git-tools]]
>  === Generate your patch using Git tools out of your commits.

Re: [PATCH v2 7/9] SubmittingPatches: clarify GitHub visual

[Junio C Hamano]

"Josh Soref via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Josh Soref <jsoref@gmail.com>
>
> GitHub has two general forms for its states, sometimes they're a simple
> colored object (e.g. green check or red x), and sometimes there's also a
> colored container (e.g. green box or red circle) with containing that
> object (e.g. check or x).
>
> That's a lot of words to try to describe things, but in general, the key
> for a failure is that it's recognized as an `x` and that it's associated
> with the color red -- the color of course is problematic for people who
> are red-green color-blind, but that's why they are paired with distinct
> shapes.
>
> Using the term `cross` doesn't really help.

I am not sure if this is accurate.  Using `x` alone does not help,
either.

I think this was raised during the review of the initial round, but
...

>  If a branch did not pass all test cases then it is marked with a red
> -cross. In that case you can click on the failing job and navigate to
> ++x+. In that case you can click on the failing job and navigate to

... it would help if we added something like ", instead of a green
checkmark" after "with a red x".  It will make the contrast with the
succeeding case stronger.  IOW, we can take advantage of the idea to
use "pair with distinct shapes and colors" ourselves.

>  "ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You
>  can also download "Artifacts" which are tarred (or zipped) archives
>  with test data relevant for debugging.

Re: [PATCH v2 2/9] CodingGuidelines: write punctuation marks

[Josh Soref]

Junio C Hamano wrote:
> Nobody seems to have commented on this step in the previous round,
> but I do not understand what you mean by ...
>
> > From: Josh Soref <jsoref@gmail.com>
> > - Match style in Release Notes
>
> ... at all.  The patch text is fine, though.

https://github.com/gitgitgadget/git/blob/692be87cbba55e8488f805d236f2ad50483bd7d5/Documentation/RelNotes/2.43.0.txt#L221

Re: [PATCH v2 1/9] CodingGuidelines: move period inside parentheses

[Josh Soref]

Junio C Hamano wrote:
> > From: Josh Soref <jsoref@gmail.com>
> >
> > The contents within parenthesis should be omittable without resulting
> > in broken text.
> >
> > Eliding the parenthesis left a period to end a run without any content.
>
> Nobody seems to have commented on this one in the previous round,
> but quite honestly, for this particular instance, I suspect that it
> may become easier to read if we just lost these parentheses, as the
> next sentence "You do not have to include more than ..." is just a
> bit of extra material to support the first sentence like the one we
> see in the parentheses.  Alternatively, moving that "You do not have
> to" also inside the same parentheses might work slightly better.

> It might be even easier to follow if we moved the list of "approved
> headers" (and the "You do not have to ... more than one" note that
> supports the "currently approved list") totally out of line by
> making it a side note.

I think, in principle, it'd be better if it was its own thing, but the
structure of this entire section makes this really hard -- I certainly
can't imagine a way to do it.

The laziest fix is:

- The first #include in C files, except in platform specific compat/
implementations and sha1dc/, must be one of "git-compat-util.h",
"builtin.h", "t/helper/test-tool.h", "xdiff/xinclude.h", or
"reftable/system.h".

Beyond that, I don't understand how to parse:
 You do not have to include more than one of these.

(Sorry, I'd like to be slightly ignorant of the C parts of git --
let's ignore that I've been blamed for at least one change to them --
so, I'm not going to look.)

Re: [PATCH v2 5/9] SubmittingPatches: update extra tags list

[Josh Soref]

Junio C Hamano wrote:
> "Josh Soref via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > +. `Co-authored-by:` is used to indicate that people exchanged drafts
> > +   of a patch before submitting it.
>
> I am afraid this misses the essence of what Co-authoring means.
> You may have shared your draft as FYI to your colleagues, and they
> may have tweaked phrasing and responded with their reviews to help
> you improve _your_ work, but that may not make them your Co-authors.
>
> I think the "intent" counts more.  If people closely worked
> together, exchanging drafts and agreeing on the final version among
> themselves before submitting, with the understanding that they share
> the authorship credit/blame, they are Co-authors.

. `Co-authored-by:` is used to indicate that people collaborated on the
   contents of a patch before submitting it.

?

Re: [PATCH v2 2/9] CodingGuidelines: write punctuation marks

[Junio C Hamano]

Josh Soref <jsoref@gmail.com> writes:

> Junio C Hamano wrote:
>> Nobody seems to have commented on this step in the previous round,
>> but I do not understand what you mean by ...
>>
>> > From: Josh Soref <jsoref@gmail.com>
>> > - Match style in Release Notes
>>
>> ... at all.  The patch text is fine, though.
>
> https://github.com/gitgitgadget/git/blob/692be87cbba55e8488f805d236f2ad50483bd7d5/Documentation/RelNotes/2.43.0.txt#L221

You mean just a single mention of the phrase?  If so, you should
pinpoint it, e.g. "The release notes for Git 2.43 calls them
'punctuation marks', so let's use that here, too" or something like
that.

Unless you are sure that all the issues of Release Notes have and
will consistently say "punctuation marks" and never say
"punctuations", that is.

Re: [PATCH v2 1/9] CodingGuidelines: move period inside parentheses

[Dragan Simic]

On 2023-12-21 22:03, Junio C Hamano wrote:
> "Josh Soref via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
>> From: Josh Soref <jsoref@gmail.com>
>> 
>> The contents within parenthesis should be omittable without resulting
>> in broken text.
>> 
>> Eliding the parenthesis left a period to end a run without any 
>> content.
> 
> Nobody seems to have commented on this one in the previous round,
> but quite honestly, for this particular instance, I suspect that it
> may become easier to read if we just lost these parentheses, as the
> next sentence "You do not have to include more than ..." is just a
> bit of extra material to support the first sentence like the one we
> see in the parentheses.  Alternatively, moving that "You do not have
> to" also inside the same parentheses might work slightly better.

I agree with simply erasing the parentheses, it makes the paragraph flow 
much better.

> It might be even easier to follow if we moved the list of "approved
> headers" (and the "You do not have to ... more than one" note that
> supports the "currently approved list") totally out of line by
> making it a side note.
> 
>> Signed-off-by: Josh Soref <jsoref@gmail.com>
>> ---
>>  Documentation/CodingGuidelines | 2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>> 
>> diff --git a/Documentation/CodingGuidelines 
>> b/Documentation/CodingGuidelines
>> index 8ed517a5ca0..af94ed3a75d 100644
>> --- a/Documentation/CodingGuidelines
>> +++ b/Documentation/CodingGuidelines
>> @@ -450,7 +450,7 @@ For C programs:
>>     one of the approved headers that includes it first for you.  (The
>>     approved headers currently include "builtin.h",
>>     "t/helper/test-tool.h", "xdiff/xinclude.h", or
>> -   "reftable/system.h").  You do not have to include more than one of
>> +   "reftable/system.h".)  You do not have to include more than one of
>>     these.
>> 
>>   - A C file must directly include the header files that declare the

[PATCH v3 0/9] Minor improvements to CodingGuidelines and SubmittingPatches

[Josh Soref via GitGitGadget]

These are a bunch of things I've run into over my past couple of attempts to
contribute to Git.

 * Incremental punctuation/grammatical improvements
 * Update extra tags suggestions based on common usage
 * drop reference to an article that was discontinued over a decade ago
 * update GitHub references
 * harmonize non-ASCII while I'm here

Note that I'm trying to do things "in the neighborhood". It'll be slower
than me replacing things topically, but hopefully easier for others to
digest. My current estimate is a decade or two :).

Josh Soref (9):
  CodingGuidelines: move period inside parentheses
  CodingGuidelines: write punctuation marks
  SubmittingPatches: drop ref to "What's in git.git"
  SubmittingPatches: discourage new trailers
  SubmittingPatches: update extra tags list
  SubmittingPatches: provide tag naming advice
  SubmittingPatches: clarify GitHub visual
  SubmittingPatches: clarify GitHub artifact format
  SubmittingPatches: hyphenate non-ASCII

 Documentation/CodingGuidelines  |  4 ++--
 Documentation/SubmittingPatches | 33 +++++++++++++++++++++++----------
 2 files changed, 25 insertions(+), 12 deletions(-)


base-commit: 624eb90fa8f65a79396615f3c2842ac5a3743350
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1623%2Fjsoref%2Fdocumentation-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1623/jsoref/documentation-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/1623

Range-diff vs v2:

  1:  b9a8eb6aa4e =  1:  b9a8eb6aa4e CodingGuidelines: move period inside parentheses
  2:  c0db8336e51 =  2:  c0db8336e51 CodingGuidelines: write punctuation marks
  3:  22d66c5b78a =  3:  22d66c5b78a SubmittingPatches: drop ref to "What's in git.git"
  4:  eac2211332f =  4:  eac2211332f SubmittingPatches: discourage new trailers
  5:  8848572fe2c =  5:  8848572fe2c SubmittingPatches: update extra tags list
  6:  8f16c7caa73 !  6:  f28c1011ba9 SubmittingPatches: improve extra tags advice
     @@ Metadata
      Author: Josh Soref <jsoref@gmail.com>
      
       ## Commit message ##
     -    SubmittingPatches: improve extra tags advice
     +    SubmittingPatches: provide tag naming advice
      
          Current statistics show a strong preference to only capitalize the first
          letter in a hyphenated tag, but that some guidance would be helpful:
     @@ Documentation/SubmittingPatches: While you can also create your own trailer if t
       encourage you to instead use one of the common trailers in this project
       highlighted above.
       
     -+Extra tags should only capitalize the very first letter, i.e. favor
     ++Only capitalize the very first letter of tags, i.e. favor
      +"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By".
      +
       [[git-tools]]
  7:  cdb5fd0957f <  -:  ----------- SubmittingPatches: clarify GitHub visual
  8:  77576327df8 !  7:  49cef6f7c20 SubmittingPatches: clarify GitHub artifact format
     @@ Metadata
      Author: Josh Soref <jsoref@gmail.com>
      
       ## Commit message ##
     -    SubmittingPatches: clarify GitHub artifact format
     +    SubmittingPatches: clarify GitHub visual
      
     -    GitHub wraps artifacts generated by workflows in a .zip file.
     +    GitHub has two general forms for its states, sometimes they're a simple
     +    colored object (e.g. green check or red x), and sometimes there's also a
     +    colored container (e.g. green box or red circle) which contains that
     +    object (e.g. check or x).
      
     -    Internally, workflows can package anything they like in them.
     -
     -    A recently generated failure artifact had the form:
     -
     -    windows-artifacts.zip
     -      Length      Date    Time    Name
     -    ---------  ---------- -----   ----
     -     76001695  12-19-2023 01:35   artifacts.tar.gz
     -     11005650  12-19-2023 01:35   tracked.tar.gz
     -    ---------                     -------
     -     87007345                     2 files
     +    That's a lot of words to try to describe things, but in general, the key
     +    for a failure is that it's recognized as an `x` and that it's associated
     +    with the color red -- the color of course is problematic for people who
     +    are red-green color-blind, but that's why they are paired with distinct
     +    shapes.
      
          Signed-off-by: Josh Soref <jsoref@gmail.com>
      
       ## Documentation/SubmittingPatches ##
     -@@ Documentation/SubmittingPatches: branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/ma
     - If a branch did not pass all test cases then it is marked with a red
     - +x+. In that case you can click on the failing job and navigate to
     - "ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You
     +@@ Documentation/SubmittingPatches: After the initial setup, CI will run whenever you push new changes
     + to your fork of Git on GitHub.  You can monitor the test state of all your
     + branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml`
     + 
     +-If a branch did not pass all test cases then it is marked with a red
     +-cross. In that case you can click on the failing job and navigate to
     +-"ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You
      -can also download "Artifacts" which are tarred (or zipped) archives
     -+can also download "Artifacts" which are zip archives containing
     -+tarred (or zipped) archives
     - with test data relevant for debugging.
     +-with test data relevant for debugging.
     ++If a branch does not pass all test cases then it will be marked with a
     ++red +x+, instead of a green check. In that case, you can click on the
     ++failing job and navigate to "ci/run-build-and-tests.sh" and/or
     ++"ci/print-test-failures.sh". You can also download "Artifacts" which
     ++are tarred (or zipped) archives with test data relevant for debugging.
       
       Then fix the problem and push your fix to your GitHub fork. This will
     + trigger a new CI build to ensure all tests pass.
  -:  ----------- >  8:  deb1bf02f3a SubmittingPatches: clarify GitHub artifact format
  9:  a4878f58fe4 =  9:  b1b75cc6a3e SubmittingPatches: hyphenate non-ASCII

-- 
gitgitgadget

[PATCH v3 1/9] CodingGuidelines: move period inside parentheses

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

The contents within parenthesis should be omittable without resulting
in broken text.

Eliding the parenthesis left a period to end a run without any content.

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/CodingGuidelines | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 8ed517a5ca0..af94ed3a75d 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -450,7 +450,7 @@ For C programs:
    one of the approved headers that includes it first for you.  (The
    approved headers currently include "builtin.h",
    "t/helper/test-tool.h", "xdiff/xinclude.h", or
-   "reftable/system.h").  You do not have to include more than one of
+   "reftable/system.h".)  You do not have to include more than one of
    these.
 
  - A C file must directly include the header files that declare the
-- 
gitgitgadget

[PATCH v3 2/9] CodingGuidelines: write punctuation marks

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

- Match style in Release Notes

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/CodingGuidelines | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index af94ed3a75d..578587a4715 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -578,7 +578,7 @@ Externally Visible Names
    . The variable name describes the effect of tweaking this knob.
 
    The section and variable names that consist of multiple words are
-   formed by concatenating the words without punctuations (e.g. `-`),
+   formed by concatenating the words without punctuation marks (e.g. `-`),
    and are broken using bumpyCaps in documentation as a hint to the
    reader.
 
-- 
gitgitgadget

[PATCH v3 3/9] SubmittingPatches: drop ref to "What's in git.git"

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

"What's in git.git" was last seen in 2010:
  https://lore.kernel.org/git/?q=%22what%27s+in+git.git%22
  https://lore.kernel.org/git/7vaavikg72.fsf@alter.siamese.dyndns.org/

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index bce7f97815c..32e90238777 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -570,7 +570,7 @@ their trees themselves.
   master).
 
 * Read the Git mailing list, the maintainer regularly posts messages
-  entitled "What's cooking in git.git" and "What's in git.git" giving
+  entitled "What's cooking in git.git" giving
   the status of various proposed changes.
 
 == GitHub CI[[GHCI]]
-- 
gitgitgadget

[PATCH v3 4/9] SubmittingPatches: discourage new trailers

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

There seems to be consensus amongst the core Git community on a working
set of common trailers, and there are non-trivial costs to people
inventing new trailers (research to discover what they mean/how they
differ from existing trailers) such that inventing new ones is generally
unwarranted and not something to be recommended to new contributors.

Suggested-by: Elijah Newren <newren@gmail.com>
Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 32e90238777..58dfe405049 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -356,8 +356,9 @@ If you like, you can put extra tags at the end:
 . `Tested-by:` is used to indicate that the person applied the patch
   and found it to have the desired effect.
 
-You can also create your own tag or use one that's in common usage
-such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
+While you can also create your own trailer if the situation warrants it, we
+encourage you to instead use one of the common trailers in this project
+highlighted above.
 
 [[git-tools]]
 === Generate your patch using Git tools out of your commits.
-- 
gitgitgadget

[PATCH v3 5/9] SubmittingPatches: update extra tags list

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

Add items with at least 100 uses in the past three years:
- Co-authored-by
- Helped-by
- Mentored-by
- Suggested-by

git log --since=3.years|
  perl -ne 'next unless /^\s+[A-Z][a-z]+-\S+:/;s/^\s+//;s/:.*/:/;print'|
  sort|uniq -c|sort -n|grep '[0-9][0-9] '
  14 Based-on-patch-by:
  14 Original-patch-by:
  17 Tested-by:
 100 Suggested-by:
 121 Co-authored-by:
 163 Mentored-by:
 274 Reported-by:
 290 Acked-by:
 450 Helped-by:
 602 Reviewed-by:
14111 Signed-off-by:

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 58dfe405049..31878cb70b7 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -355,6 +355,14 @@ If you like, you can put extra tags at the end:
   patch after a detailed analysis.
 . `Tested-by:` is used to indicate that the person applied the patch
   and found it to have the desired effect.
+. `Co-authored-by:` is used to indicate that people exchanged drafts
+   of a patch before submitting it.
+. `Helped-by:` is used to credit someone who suggested ideas for
+  changes without providing the precise changes in patch form.
+. `Mentored-by:` is used to credit someone with helping develop a
+  patch as part of a mentorship program (e.g., GSoC or Outreachy).
+. `Suggested-by:` is used to credit someone with suggesting the idea
+  for a patch.
 
 While you can also create your own trailer if the situation warrants it, we
 encourage you to instead use one of the common trailers in this project
-- 
gitgitgadget

[PATCH v3 6/9] SubmittingPatches: provide tag naming advice

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

Current statistics show a strong preference to only capitalize the first
letter in a hyphenated tag, but that some guidance would be helpful:

git log |
  perl -ne 'next unless /^\s+(?:Signed-[oO]ff|Acked)-[bB]y:/;
    s/^\s+//;s/:.*/:/;print'|
  sort|uniq -c|sort -n
   2 Signed-off-By:
   4 Signed-Off-by:
  22 Acked-By:
  47 Signed-Off-By:
2202 Acked-by:
95315 Signed-off-by:

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 31878cb70b7..94c874ab5e6 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -368,6 +368,9 @@ While you can also create your own trailer if the situation warrants it, we
 encourage you to instead use one of the common trailers in this project
 highlighted above.
 
+Only capitalize the very first letter of tags, i.e. favor
+"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By".
+
 [[git-tools]]
 === Generate your patch using Git tools out of your commits.
 
-- 
gitgitgadget

[PATCH v3 7/9] SubmittingPatches: clarify GitHub visual

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

GitHub has two general forms for its states, sometimes they're a simple
colored object (e.g. green check or red x), and sometimes there's also a
colored container (e.g. green box or red circle) which contains that
object (e.g. check or x).

That's a lot of words to try to describe things, but in general, the key
for a failure is that it's recognized as an `x` and that it's associated
with the color red -- the color of course is problematic for people who
are red-green color-blind, but that's why they are paired with distinct
shapes.

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 94c874ab5e6..0665f89f38c 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -602,11 +602,11 @@ After the initial setup, CI will run whenever you push new changes
 to your fork of Git on GitHub.  You can monitor the test state of all your
 branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml`
 
-If a branch did not pass all test cases then it is marked with a red
-cross. In that case you can click on the failing job and navigate to
-"ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You
-can also download "Artifacts" which are tarred (or zipped) archives
-with test data relevant for debugging.
+If a branch does not pass all test cases then it will be marked with a
+red +x+, instead of a green check. In that case, you can click on the
+failing job and navigate to "ci/run-build-and-tests.sh" and/or
+"ci/print-test-failures.sh". You can also download "Artifacts" which
+are tarred (or zipped) archives with test data relevant for debugging.
 
 Then fix the problem and push your fix to your GitHub fork. This will
 trigger a new CI build to ensure all tests pass.
-- 
gitgitgadget

[PATCH v3 8/9] SubmittingPatches: clarify GitHub artifact format

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

GitHub wraps artifacts generated by workflows in a .zip file.

Internally, workflows can package anything they like in them.

A recently generated failure artifact had the form:

windows-artifacts.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
 76001695  12-19-2023 01:35   artifacts.tar.gz
 11005650  12-19-2023 01:35   tracked.tar.gz
---------                     -------
 87007345                     2 files

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 0665f89f38c..5e2e13b5e09 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -606,7 +606,8 @@ If a branch does not pass all test cases then it will be marked with a
 red +x+, instead of a green check. In that case, you can click on the
 failing job and navigate to "ci/run-build-and-tests.sh" and/or
 "ci/print-test-failures.sh". You can also download "Artifacts" which
-are tarred (or zipped) archives with test data relevant for debugging.
+are zip archives containing tarred (or zipped) archives with test data
+relevant for debugging.
 
 Then fix the problem and push your fix to your GitHub fork. This will
 trigger a new CI build to ensure all tests pass.
-- 
gitgitgadget

[PATCH v3 9/9] SubmittingPatches: hyphenate non-ASCII

[Josh Soref via GitGitGadget]

From: Josh Soref <jsoref@gmail.com>

Git documentation does this with the exception of ancient release notes.

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 5e2e13b5e09..e734a3f0f17 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -699,7 +699,7 @@ message to an external program, and this is a handy way to drive
 `git am`.  However, if the message is MIME encoded, what is
 piped into the program is the representation you see in your
 `*Article*` buffer after unwrapping MIME.  This is often not what
-you would want for two reasons.  It tends to screw up non ASCII
+you would want for two reasons.  It tends to screw up non-ASCII
 characters (most notably in people's names), and also
 whitespaces (fatal in patches).  Running "C-u g" to display the
 message in raw form before using "|" to run the pipe can work
-- 
gitgitgadget