Minor improvements to CodingGuidelines and SubmittingPatches

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

From: Josh Soref <[email protected]>

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.

---
 Documentation/CodingGuidelines | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 8ed517a5ca0..af94ed3a75d 100644
@@ -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

From: Josh Soref <[email protected]>

- Match style in Release Notes

---
 Documentation/CodingGuidelines | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index af94ed3a75d..578587a4715 100644
@@ -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

From: Josh Soref <[email protected]>

"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/[email protected]/

---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index bce7f97815c..32e90238777 100644
@@ -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

From: Josh Soref <[email protected]>

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:

---
 Documentation/SubmittingPatches | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

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.
 . `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

Hi Josh

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.

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

To add to what Phillip said...

Same.

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.

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

Agreed.

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

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.

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.

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

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.

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

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

Anyway, see all of us struggle with it below:

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.

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.

[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

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.

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.

?

Right.

Let's have some fun (inception):

commit eac2211332f754c5f4127a58aafb9882bfe939e8

Author: Josh Soref <[email protected]>
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.

index 32e9023877..58dfe40504 100644
@@ -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.

Hi Josh

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.

From: Josh Soref <[email protected]>

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:

---
 Documentation/SubmittingPatches | 3 +++
 1 file changed, 3 insertions(+)

index 694a7bafb68..d7a84f59478 100644
@@ -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

From: Josh Soref <[email protected]>

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.

---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index d7a84f59478..8e19c7f82e4 100644
@@ -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

Am 19.12.23 um 09:41 schrieb Josh Soref via GitGitGadget:

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.

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

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."?

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

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".

(sheepishly raises hand). Thanks for being considerate.

I 100% agree with this.

Thanks.

From: Josh Soref <[email protected]>

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

---
 Documentation/SubmittingPatches | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

index 8e19c7f82e4..b4fa52ae348 100644
@@ -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

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.

From: Josh Soref <[email protected]>

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

---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index b4fa52ae348..3c53592cfc8 100644
@@ -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

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.

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 <[email protected]>

## 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 <[email protected]>

## 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

## 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.

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

From: Josh Soref <[email protected]>

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.

---
 Documentation/CodingGuidelines | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 8ed517a5ca0..af94ed3a75d 100644
@@ -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

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.)

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

From: Josh Soref <[email protected]>

- Match style in Release Notes

---
 Documentation/CodingGuidelines | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

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

gitgitgadget

"Josh Soref via GitGitGadget" <[email protected]> writes:

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

... 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.

From: Josh Soref <[email protected]>

"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/[email protected]/

---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index bce7f97815c..32e90238777 100644
@@ -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

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.

From: Josh Soref <[email protected]>

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.

---
 Documentation/SubmittingPatches | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

index 32e90238777..58dfe405049 100644
@@ -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

From: Josh Soref <[email protected]>

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:

---
 Documentation/SubmittingPatches | 8 ++++++++
 1 file changed, 8 insertions(+)

index 58dfe405049..31878cb70b7 100644
@@ -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

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.

?

From: Josh Soref <[email protected]>

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:

---
 Documentation/SubmittingPatches | 3 +++
 1 file changed, 3 insertions(+)

index 31878cb70b7..4476b52a50f 100644
@@ -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

From: Josh Soref <[email protected]>

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.

---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 4476b52a50f..8f79253c5cb 100644
@@ -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

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
...

... 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.

From: Josh Soref <[email protected]>

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

---
 Documentation/SubmittingPatches | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

index 8f79253c5cb..cb0dcce6a17 100644
@@ -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

From: Josh Soref <[email protected]>

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

---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index cb0dcce6a17..9283eb0ef71 100644
@@ -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

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 <[email protected]>

## 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 <[email protected]>

## 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.

## 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

From: Josh Soref <[email protected]>

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.

---
 Documentation/CodingGuidelines | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 8ed517a5ca0..af94ed3a75d 100644
@@ -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

From: Josh Soref <[email protected]>

- Match style in Release Notes

---
 Documentation/CodingGuidelines | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index af94ed3a75d..578587a4715 100644
@@ -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

From: Josh Soref <[email protected]>

"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/[email protected]/

---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index bce7f97815c..32e90238777 100644
@@ -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

From: Josh Soref <[email protected]>

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.

---
 Documentation/SubmittingPatches | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

index 32e90238777..58dfe405049 100644
@@ -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

From: Josh Soref <[email protected]>

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:

---
 Documentation/SubmittingPatches | 8 ++++++++
 1 file changed, 8 insertions(+)

index 58dfe405049..31878cb70b7 100644
@@ -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

From: Josh Soref <[email protected]>

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:

---
 Documentation/SubmittingPatches | 3 +++
 1 file changed, 3 insertions(+)

index 31878cb70b7..94c874ab5e6 100644
@@ -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

From: Josh Soref <[email protected]>

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.

---
 Documentation/SubmittingPatches | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

index 94c874ab5e6..0665f89f38c 100644
@@ -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

From: Josh Soref <[email protected]>

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

---
 Documentation/SubmittingPatches | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

index 0665f89f38c..5e2e13b5e09 100644
@@ -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

From: Josh Soref <[email protected]>

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

---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 5e2e13b5e09..e734a3f0f17 100644
@@ -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