Skip to contentSkip to conversation

Small updates to SubmittingPatches

PATCH Superseded Junio C Hamano 5 participants 16 messages Jun 2 – Jun 4 Documentation

lore
Share & tools
lore
#0 lore raw

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

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

 Documentation/SubmittingPatches | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)
Signature · 1 line
2.54.0-567-gf25c749695
#1 lore raw

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.

---
 Documentation/SubmittingPatches | 1 +
 1 file changed, 1 insertion(+)
Documentation/SubmittingPatches +1 -0
index d570184ec8..dec8aea4cb 100644
@@ -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
Signature · 1 line
2.54.0-567-gf25c749695
#2 lore raw

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

Quoted 5 lines · 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.

s/typofies/typofixes/

Thanks.

#3 lore raw

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

Quoted 10 lines · Christian Couder
Quoted 5 lines · 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.

s/typofies/typofixes/

Thanks.

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

#4 lore raw

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

Quoted 9 lines · Junio C Hamano
Quoted 3 lines · Christian Couder

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

#5 lore raw

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

In reply to Junio C Hamano
Quoted 7 lines · 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.

---

Imperative mood?

#6 lore raw

PATCH 2/2 SubmittingPatches: describe cover letter

In reply to 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.

---
 Documentation/SubmittingPatches | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
Documentation/SubmittingPatches +19 -0
index dec8aea4cb..8ff1792b9b 100644
@@ -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)
 
Signature · 1 line
2.54.0-567-gf25c749695
#7 lore raw

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

Quoted 2 lines · 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

s/to widest/to the widest/?

Quoted 22 lines

possible audience.

---
 Documentation/SubmittingPatches | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
Documentation/SubmittingPatches +7 -0
index dec8aea4cb..8ff1792b9b 100644
@@ -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.
+

Documentation/SubmittingPatches highlighted above. · line 491

Quoted 10 lines
Documentation/SubmittingPatches +10 -0
+. 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

#8 lore raw

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

Quoted 5 lines · Patrick Steinhardt
Quoted 2 lines · 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

s/to widest/to the widest/?

Thanks.

Quoted 15 lines
Quoted 15 lines

+[[cover-letter]]
+=== Cover Letter

Documentation/SubmittingPatches +13 -0
+
+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.
+
Quoted 8 lines
Quoted 2 lines

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

#9 lore raw

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

In reply to Junio C Hamano
Quoted 3 lines · 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.

This is a good thing to boost in the documentation.

Documentation/SubmittingPatches highlighted above. · line 483

Quoted 9 lines

+[[cover-letter]]
+=== Cover Letter

Documentation/SubmittingPatches +7 -0
+
+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.

Documentation/SubmittingPatches highlighted above. · line 491

Quoted 7 lines

+. For a second or subsequent iteration of the same topic, make sure

Documentation/SubmittingPatches +6 -0
+  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

#10 lore raw

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

Quoted 7 lines · Derrick Stolee
Quoted 2 lines

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

Quoted 6 lines

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

Quoted 11 lines

Documentation/SubmittingPatches highlighted above. · line 491

Quoted 7 lines

+. For a second or subsequent iteration of the same topic, make sure

Documentation/SubmittingPatches +6 -0
+  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.

#11 lore raw

v2 cover Small updates to SubmittingPatches

In reply to 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(+)
Signature · 1 line
2.54.0-591-g9032776dcc
#12 lore raw

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.

---
 Documentation/SubmittingPatches | 1 +
 1 file changed, 1 insertion(+)
Documentation/SubmittingPatches +1 -0
index d570184ec8..dec8aea4cb 100644
@@ -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
Signature · 1 line
2.54.0-591-g9032776dcc
#13 lore raw

PATCH v2 2/2 SubmittingPatches: describe cover letter

In reply to 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.

---
 Documentation/SubmittingPatches | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
Documentation/SubmittingPatches +24 -0
index dec8aea4cb..df9f722bfe 100644
@@ -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)
 
Signature · 1 line
2.54.0-591-g9032776dcc
#14 lore raw
In reply to Junio C Hamano
Quoted 8 lines · 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.

This version LGTM.

Thanks,
-Stolee

#15 lore raw
Quoted 10 lines · Derrick Stolee
Quoted 8 lines · 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.

This version LGTM.

Agreed, I'm happy with this version.

Patrick