News and archive of git@vger.kernel.org, since April 2005
16 messages between Jun 2, 2026 and Jun 4, 2026, from Junio C Hamano, Patrick Steinhardt, Derrick Stolee, Christian Couder, Kristoffer Haugsbakk.
Plain Markdown or JSON for tools and agents. Diffs are folded; open one to read it.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
Re: [PATCH v2 0/2] Small updates to SubmittingPatches
On Tue, Jun 02, 2026 at 11:24:48AM -0400, Derrick Stolee wrote:
> 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.
Agreed, I'm happy with this version.
Patrick