[PATCH 0/2] Small updates to SubmittingPatches

[PATCH 0/2] Small updates to SubmittingPatches

[Junio C Hamano]

Recently I gave some advice on how a cover letter should
try to sell the idea to widest possible audience, and then
I realized that we do not seem to teach how in our guides.

Here is a small series to do so.

 1/2: SubmittingPatches: separate typofixes section
 2/2: SubmittingPatches: describe cover letter

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

-- 
2.54.0-567-gf25c749695

[PATCH 1/2] SubmittingPatches: separate typofixes section

[Junio C Hamano]

The existing text said something about tests (with [[tests]] to make
it easier to refer to it from elsewhere) and then flowed into a
different topic of typofixes, but it was unclear where the latter
started.  Add a similar [[typofies]] marker to the document.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/SubmittingPatches | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index d570184ec8..dec8aea4cb 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -237,6 +237,7 @@ Do not forget to update the documentation to describe the updated
 behavior and make sure that the resulting documentation set formats
 well (try the Documentation/doc-diff script).
 
+[[typofixes]]
 We currently have a liberal mixture of US and UK English norms for
 spelling and grammar, which is somewhat unfortunate.  A huge patch that
 touches the files all over the place only to correct the inconsistency
-- 
2.54.0-567-gf25c749695

[PATCH 2/2] SubmittingPatches: describe cover letter

[Junio C Hamano]

We talk about how a commit log message should look like, but do not
give advice on writing the cover letter to sell a series to widest
possible audience.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/SubmittingPatches | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index dec8aea4cb..8ff1792b9b 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -472,6 +472,25 @@ highlighted above.
 Only capitalize the very first letter of the trailer, i.e. favor
 "Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By".
 
+[[cover-letter]]
+=== Cover Letter
+
+The purpose of your cover letter is to sell your changes, explain what
+they are about, and get your target audience interested enough to read
+the patches.
+
+. Make sure your target audience can understand what the patches are
+  about and why they are needed without prior context.
+
+. For a second or subsequent iteration of the same topic, make sure
+  people who missed the earlier discussion can still understand what
+  the patches are about, so they can judge if the topic is worth their
+  time to read and comment on.
+
+. To help those who are familiar with earlier iterations, give a
+  summary of changes since the previous rounds.
+
+
 [[ai]]
 === Use of Artificial Intelligence (AI)
 
-- 
2.54.0-567-gf25c749695

Re: [PATCH 2/2] SubmittingPatches: describe cover letter

[Patrick Steinhardt]

On Tue, Jun 02, 2026 at 06:08:08PM +0900, Junio C Hamano wrote:
> We talk about how a commit log message should look like, but do not
> give advice on writing the cover letter to sell a series to widest

s/to widest/to the widest/?

> possible audience.
> 
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  Documentation/SubmittingPatches | 19 +++++++++++++++++++
>  1 file changed, 19 insertions(+)
> 
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index dec8aea4cb..8ff1792b9b 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -472,6 +472,25 @@ highlighted above.
>  Only capitalize the very first letter of the trailer, i.e. favor
>  "Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By".
>  
> +[[cover-letter]]
> +=== Cover Letter
> +
> +The purpose of your cover letter is to sell your changes, explain what
> +they are about, and get your target audience interested enough to read
> +the patches.
> +
> +. Make sure your target audience can understand what the patches are
> +  about and why they are needed without prior context.
> +
> +. For a second or subsequent iteration of the same topic, make sure
> +  people who missed the earlier discussion can still understand what
> +  the patches are about, so they can judge if the topic is worth their
> +  time to read and comment on.
> +
> +. To help those who are familiar with earlier iterations, give a
> +  summary of changes since the previous rounds.

We might also recommend to include a range-diff in subsequent
iterations. That being said though, I just sent a small series to the
mailing list that recommends using b4, and there it get this for free.
So no idea whether it's still worth it to then cover this here
explicitly.

Patrick

Re: [PATCH 2/2] SubmittingPatches: describe cover letter

[Derrick Stolee]

On 6/2/2026 5:08 AM, Junio C Hamano wrote:
> We talk about how a commit log message should look like, but do not
> give advice on writing the cover letter to sell a series to widest
> possible audience.

This is a good thing to boost in the documentation.

> +[[cover-letter]]
> +=== Cover Letter
> +
> +The purpose of your cover letter is to sell your changes, explain what
> +they are about, and get your target audience interested enough to read
> +the patches.
> +
> +. Make sure your target audience can understand what the patches are
> +  about and why they are needed without prior context.

The thing that I like to say about the cover letter is that this is
your opportunity to communicate why the value of your change is worth
the risk of regressions and the cost of maintenance. Perhaps:

. Every code change comes with risk of regression and maintenance cost.
  The cover letter should clearly communicate why the value of your
  proposed change is worth applying. You can also describe how the risk
  is reduced by the design choices you made while writing the patches.

Or something similar may be helpful? I may just be over explaining.

> +. For a second or subsequent iteration of the same topic, make sure
> +  people who missed the earlier discussion can still understand what
> +  the patches are about, so they can judge if the topic is worth their
> +  time to read and comment on.
> +
> +. To help those who are familiar with earlier iterations, give a
> +  summary of changes since the previous rounds.
I find these updates to be particularly helpful, even for GitGitGadget
PRs that include a range-diff automatically. It's good to double-check
the human description of the update against the computed diff.

Thanks,
-Stolee

Re: [PATCH 2/2] SubmittingPatches: describe cover letter

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> On Tue, Jun 02, 2026 at 06:08:08PM +0900, Junio C Hamano wrote:
>> We talk about how a commit log message should look like, but do not
>> give advice on writing the cover letter to sell a series to widest
>
> s/to widest/to the widest/?

Thanks.

>> +[[cover-letter]]
>> +=== Cover Letter
>> +
>> +The purpose of your cover letter is to sell your changes, explain what
>> +they are about, and get your target audience interested enough to read
>> +the patches.
>> +
>> +. Make sure your target audience can understand what the patches are
>> +  about and why they are needed without prior context.
>> +
>> +. For a second or subsequent iteration of the same topic, make sure
>> +  people who missed the earlier discussion can still understand what
>> +  the patches are about, so they can judge if the topic is worth their
>> +  time to read and comment on.
>> +
>> +. To help those who are familiar with earlier iterations, give a
>> +  summary of changes since the previous rounds.
>
> We might also recommend to include a range-diff in subsequent
> iterations. That being said though, I just sent a small series to the
> mailing list that recommends using b4, and there it get this for free.
> So no idea whether it's still worth it to then cover this here
> explicitly.

I think these are orthogonal.  What b4 helps you with is the shape
of the letter, how it looks like.  This update is about the contents
in the letter, what you convey to your readers.

Of course, "format-patch --cover-letter" also lets you do range-diff
or interdiff, so they come for free.  But the above description is
not tied to any particular tool to prepare your cover letter.

Re: [PATCH 2/2] SubmittingPatches: describe cover letter

[Junio C Hamano]

Derrick Stolee <stolee@gmail.com> writes:

>> +. Make sure your target audience can understand what the patches are
>> +  about and why they are needed without prior context.
>
> The thing that I like to say about the cover letter is that this is
> your opportunity to communicate why the value of your change is worth
> the risk of regressions and the cost of maintenance. Perhaps:
>
> . Every code change comes with risk of regression and maintenance cost.
>   The cover letter should clearly communicate why the value of your
>   proposed change is worth applying. You can also describe how the risk
>   is reduced by the design choices you made while writing the patches.
>
> Or something similar may be helpful? I may just be over explaining.

Yeah, it may be a bit on the heavy side, but complements what I
wanted to achieve with this update very well.  I wanted to encourage
writing for wider audience, without leaving those "not in the know"
behind.  What you wrote above is more about what to write, which is
very much appreciated.  I think it fits well as the 0th item before
the three-bullet list.

>> +. For a second or subsequent iteration of the same topic, make sure
>> +  people who missed the earlier discussion can still understand what
>> +  the patches are about, so they can judge if the topic is worth their
>> +  time to read and comment on.
>> +
>> +. To help those who are familiar with earlier iterations, give a
>> +  summary of changes since the previous rounds.
>
> I find these updates to be particularly helpful, even for GitGitGadget
> PRs that include a range-diff automatically. It's good to double-check
> the human description of the update against the computed diff.

Oh, absolutely.

A GitGitGadget generated cover letter that lack any human input but
just range-diff dump is often very hard to read, and the receiving
end is better off pretending there was no useful information in the
cover letter.  "git diff @{-1}..." after applying the patches to the
same base is sadly a lot easier to read than "git range-diff @{-1}..."
for many series.

Re: [PATCH 1/2] SubmittingPatches: separate typofixes section

[Christian Couder]

On Tue, Jun 2, 2026 at 11:13 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> The existing text said something about tests (with [[tests]] to make
> it easier to refer to it from elsewhere) and then flowed into a
> different topic of typofixes, but it was unclear where the latter
> started.  Add a similar [[typofies]] marker to the document.

s/typofies/typofixes/

Thanks.

Re: [PATCH 1/2] SubmittingPatches: separate typofixes section

[Junio C Hamano]

Christian Couder <christian.couder@gmail.com> writes:

> On Tue, Jun 2, 2026 at 11:13 AM Junio C Hamano <gitster@pobox.com> wrote:
>>
>> The existing text said something about tests (with [[tests]] to make
>> it easier to refer to it from elsewhere) and then flowed into a
>> different topic of typofixes, but it was unclear where the latter
>> started.  Add a similar [[typofies]] marker to the document.
>
> s/typofies/typofixes/
>
> Thanks.

Thanks.  It is amusing to see I cannot say typofixes when I talk
about them ;-)

[PATCH v2 0/2] Small updates to SubmittingPatches

[Junio C Hamano]

Recently I gave some advice on how a cover letter should
try to sell the idea to widest possible audience, and then
I realized that we do not seem to teach how in our guides.

Here is a small series to do so.

In this round, a few typos have been corrected, and improvements are
made thanks to help from Christian, Stolee, and Patrick.

 1/2: SubmittingPatches: separate typofixes section
 2/2: SubmittingPatches: describe cover letter

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

-- 
2.54.0-591-g9032776dcc

[PATCH v2 1/2] SubmittingPatches: separate typofixes section

[Junio C Hamano]

The existing text said something about tests (with [[tests]] to make
it easier to refer to it from elsewhere) and then flowed into a
different topic of typofixes, but it was unclear where the latter
started.  Add a similar [[typofixes]] marker to the document.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/SubmittingPatches | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index d570184ec8..dec8aea4cb 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -237,6 +237,7 @@ Do not forget to update the documentation to describe the updated
 behavior and make sure that the resulting documentation set formats
 well (try the Documentation/doc-diff script).
 
+[[typofixes]]
 We currently have a liberal mixture of US and UK English norms for
 spelling and grammar, which is somewhat unfortunate.  A huge patch that
 touches the files all over the place only to correct the inconsistency
-- 
2.54.0-591-g9032776dcc

[PATCH v2 2/2] SubmittingPatches: describe cover letter

[Junio C Hamano]

We talk about how a commit log message should look like, but do not
give advice on writing the cover letter to sell a series to the
widest possible audience.

Helped-by: Patrick Steinhardt <ps@pks.im>
Helped-by: Derrick Stolee <stolee@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/SubmittingPatches | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index dec8aea4cb..df9f722bfe 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -472,6 +472,30 @@ highlighted above.
 Only capitalize the very first letter of the trailer, i.e. favor
 "Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By".
 
+[[cover-letter]]
+=== Cover Letter
+
+The purpose of your cover letter is to sell your changes, explain what
+they are about, and get your target audience interested enough to read
+the patches.
+
+. Every code change comes with risk of regression and maintenance cost.
+  The cover letter should clearly communicate why the value of your
+  proposed change is worth applying. You can also describe how the risk
+  is reduced by the design choices you made while writing the patches.
+
+. Make sure your target audience can understand what the patches are
+  about and why they are needed without prior context.
+
+. For a second or subsequent iteration of the same topic, make sure
+  people who missed the earlier discussion can still understand what
+  the patches are about, so they can judge if the topic is worth their
+  time to read and comment on.
+
+. To help those who are familiar with earlier iterations, give a
+  summary of changes since the previous rounds.
+
+
 [[ai]]
 === Use of Artificial Intelligence (AI)
 
-- 
2.54.0-591-g9032776dcc

Re: [PATCH 1/2] SubmittingPatches: separate typofixes section

[Kristoffer Haugsbakk]

On Tue, Jun 2, 2026, at 11:08, Junio C Hamano wrote:
> The existing text said something about tests (with [[tests]] to make
> it easier to refer to it from elsewhere) and then flowed into a
> different topic of typofixes, but it was unclear where the latter
> started.  Add a similar [[typofies]] marker to the document.
>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---

Imperative mood?

Re: [PATCH 1/2] SubmittingPatches: separate typofixes section

[Christian Couder]

On Tue, Jun 2, 2026 at 4:28 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Christian Couder <christian.couder@gmail.com> writes:

> > s/typofies/typofixes/
> >
> > Thanks.
>
> Thanks.  It is amusing to see I cannot say typofixes when I talk
> about them ;-)

I wondered a bit if it was a case of satiric or ironical misspelling,
but it looks like in English the usual words for them are "grammer"
and "speling", like in:

"I am an expert in English grammer and speling." ;-)

Re: [PATCH v2 0/2] Small updates to SubmittingPatches

[Derrick Stolee]

On 6/2/2026 10:43 AM, Junio C Hamano wrote:
> Recently I gave some advice on how a cover letter should
> try to sell the idea to widest possible audience, and then
> I realized that we do not seem to teach how in our guides.
> 
> Here is a small series to do so.
> 
> In this round, a few typos have been corrected, and improvements are
> made thanks to help from Christian, Stolee, and Patrick.
This version LGTM.

Thanks,
-Stolee