Small updates to SubmittingPatches
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
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
@@ -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
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.
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 ;-)
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." ;-)
Re: [PATCH 1/2] SubmittingPatches: separate typofixes section
In reply to Junio C HamanoQuoted 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.
Signed-off-by Junio C Hamano <[email protected]>---
Imperative mood?
PATCH 2/2 SubmittingPatches: describe cover letter
In reply to Junio C HamanoWe 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
@@ -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
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.
Signed-off-by Junio C Hamano <[email protected]>--- Documentation/SubmittingPatches | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+)Documentation/SubmittingPatches +7
-0@@ -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
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 LetterDocumentation/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.
Re: [PATCH 2/2] SubmittingPatches: describe cover letter
In reply to Junio C HamanoQuoted 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 LetterDocumentation/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
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.
v2 cover Small updates to SubmittingPatches
In reply to Junio C HamanoRecently 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
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
@@ -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
PATCH v2 2/2 SubmittingPatches: describe cover letter
In reply to Junio C HamanoWe 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
@@ -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
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
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