{"thread":{"id":"65735","subject":"[PATCH 0/2] Small updates to SubmittingPatches","startedAt":"2026-06-02T09:08:11Z","lastAt":"2026-06-04T06:51:03Z","messageCount":16,"participants":["Junio C Hamano","Patrick Steinhardt","Derrick Stolee","Christian Couder","Kristoffer Haugsbakk"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"544478","messageId":"20260602090808.87837-1-gitster@pobox.com","threadId":"65735","inReplyTo":null,"subject":"[PATCH 0/2] Small updates to SubmittingPatches","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-02T09:08:06Z","receivedAt":"2026-06-02T09:08:11Z","isPatch":true,"body":"Recently I gave some advice on how a cover letter should\ntry to sell the idea to widest possible audience, and then\nI realized that we do not seem to teach how in our guides.\n\nHere is a small series to do so.\n\n 1/2: SubmittingPatches: separate typofixes section\n 2/2: SubmittingPatches: describe cover letter\n\n Documentation/SubmittingPatches | 20 ++++++++++++++++++++\n 1 file changed, 20 insertions(+)\n\n-- \n2.54.0-567-gf25c749695\n\n"},{"id":"544479","messageId":"20260602090808.87837-2-gitster@pobox.com","threadId":"65735","inReplyTo":"20260602090808.87837-1-gitster@pobox.com","subject":"[PATCH 1/2] SubmittingPatches: separate typofixes section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-02T09:08:07Z","receivedAt":"2026-06-02T09:08:12Z","isPatch":true,"body":"The existing text said something about tests (with [[tests]] to make\nit easier to refer to it from elsewhere) and then flowed into a\ndifferent topic of typofixes, but it was unclear where the latter\nstarted. Add a similar [[typofies]] marker to the document.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/SubmittingPatches | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex d570184ec8..dec8aea4cb 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -237,6 +237,7 @@ Do not forget to update the documentation to describe the updated\n behavior and make sure that the resulting documentation set formats\n well (try the Documentation/doc-diff script).\n \n+[[typofixes]]\n We currently have a liberal mixture of US and UK English norms for\n spelling and grammar, which is somewhat unfortunate. A huge patch that\n touches the files all over the place only to correct the inconsistency\n-- \n2.54.0-567-gf25c749695\n\n"},{"id":"544480","messageId":"20260602090808.87837-3-gitster@pobox.com","threadId":"65735","inReplyTo":"20260602090808.87837-1-gitster@pobox.com","subject":"[PATCH 2/2] SubmittingPatches: describe cover letter","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-02T09:08:08Z","receivedAt":"2026-06-02T09:08:14Z","isPatch":true,"body":"We talk about how a commit log message should look like, but do not\ngive advice on writing the cover letter to sell a series to widest\npossible audience.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/SubmittingPatches | 19 +++++++++++++++++++\n 1 file changed, 19 insertions(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex dec8aea4cb..8ff1792b9b 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -472,6 +472,25 @@ highlighted above.\n Only capitalize the very first letter of the trailer, i.e. favor\n \"Signed-off-by\" over \"Signed-Off-By\" and \"Acked-by:\" over \"Acked-By\".\n \n+[[cover-letter]]\n+=== Cover Letter\n+\n+The purpose of your cover letter is to sell your changes, explain what\n+they are about, and get your target audience interested enough to read\n+the patches.\n+\n+. Make sure your target audience can understand what the patches are\n+ about and why they are needed without prior context.\n+\n+. For a second or subsequent iteration of the same topic, make sure\n+ people who missed the earlier discussion can still understand what\n+ the patches are about, so they can judge if the topic is worth their\n+ time to read and comment on.\n+\n+. To help those who are familiar with earlier iterations, give a\n+ summary of changes since the previous rounds.\n+\n+\n [[ai]]\n === Use of Artificial Intelligence (AI)\n \n-- \n2.54.0-567-gf25c749695\n\n"},{"id":"544497","messageId":"ah7HZuy_WRCD9ZZ-@pks.im","threadId":"65735","inReplyTo":"20260602090808.87837-3-gitster@pobox.com","subject":"Re: [PATCH 2/2] SubmittingPatches: describe cover letter","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-02T12:07:02Z","receivedAt":"2026-06-02T12:07:08Z","isPatch":true,"body":"On Tue, Jun 02, 2026 at 06:08:08PM +0900, Junio C Hamano wrote:\n> We talk about how a commit log message should look like, but do not\n> give advice on writing the cover letter to sell a series to widest\n\ns/to widest/to the widest/?\n\n> possible audience.\n> \n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/SubmittingPatches | 19 +++++++++++++++++++\n> 1 file changed, 19 insertions(+)\n> \n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> index dec8aea4cb..8ff1792b9b 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -472,6 +472,25 @@ highlighted above.\n> Only capitalize the very first letter of the trailer, i.e. favor\n> \"Signed-off-by\" over \"Signed-Off-By\" and \"Acked-by:\" over \"Acked-By\".\n> \n> +[[cover-letter]]\n> +=== Cover Letter\n> +\n> +The purpose of your cover letter is to sell your changes, explain what\n> +they are about, and get your target audience interested enough to read\n> +the patches.\n> +\n> +. Make sure your target audience can understand what the patches are\n> + about and why they are needed without prior context.\n> +\n> +. For a second or subsequent iteration of the same topic, make sure\n> + people who missed the earlier discussion can still understand what\n> + the patches are about, so they can judge if the topic is worth their\n> + time to read and comment on.\n> +\n> +. To help those who are familiar with earlier iterations, give a\n> + summary of changes since the previous rounds.\n\nWe might also recommend to include a range-diff in subsequent\niterations. That being said though, I just sent a small series to the\nmailing list that recommends using b4, and there it get this for free.\nSo no idea whether it's still worth it to then cover this here\nexplicitly.\n\nPatrick\n"},{"id":"544498","messageId":"fd588cff-be2b-4422-9c01-cef06b2ea5fd@gmail.com","threadId":"65735","inReplyTo":"20260602090808.87837-3-gitster@pobox.com","subject":"Re: [PATCH 2/2] SubmittingPatches: describe cover letter","fromName":"Derrick Stolee","fromEmail":"stolee@gmail.com","sentAt":"2026-06-02T12:29:11Z","receivedAt":"2026-06-02T12:29:14Z","isPatch":true,"body":"On 6/2/2026 5:08 AM, Junio C Hamano wrote:\n> We talk about how a commit log message should look like, but do not\n> give advice on writing the cover letter to sell a series to widest\n> possible audience.\n\nThis is a good thing to boost in the documentation.\n\n> +[[cover-letter]]\n> +=== Cover Letter\n> +\n> +The purpose of your cover letter is to sell your changes, explain what\n> +they are about, and get your target audience interested enough to read\n> +the patches.\n> +\n> +. Make sure your target audience can understand what the patches are\n> + about and why they are needed without prior context.\n\nThe thing that I like to say about the cover letter is that this is\nyour opportunity to communicate why the value of your change is worth\nthe risk of regressions and the cost of maintenance. Perhaps:\n\n. Every code change comes with risk of regression and maintenance cost.\n The cover letter should clearly communicate why the value of your\n proposed change is worth applying. You can also describe how the risk\n is reduced by the design choices you made while writing the patches.\n\nOr something similar may be helpful? I may just be over explaining.\n\n> +. For a second or subsequent iteration of the same topic, make sure\n> + people who missed the earlier discussion can still understand what\n> + the patches are about, so they can judge if the topic is worth their\n> + time to read and comment on.\n> +\n> +. To help those who are familiar with earlier iterations, give a\n> + summary of changes since the previous rounds.\nI find these updates to be particularly helpful, even for GitGitGadget\nPRs that include a range-diff automatically. It's good to double-check\nthe human description of the update against the computed diff.\n\nThanks,\n-Stolee\n"},{"id":"544508","messageId":"xmqqh5nlvzbk.fsf@gitster.g","threadId":"65735","inReplyTo":"ah7HZuy_WRCD9ZZ-@pks.im","subject":"Re: [PATCH 2/2] SubmittingPatches: describe cover letter","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-02T13:36:47Z","receivedAt":"2026-06-02T13:36:49Z","isPatch":true,"body":"Patrick Steinhardt writes:\n\n> On Tue, Jun 02, 2026 at 06:08:08PM +0900, Junio C Hamano wrote:\n>> We talk about how a commit log message should look like, but do not\n>> give advice on writing the cover letter to sell a series to widest\n>\n> s/to widest/to the widest/?\n\nThanks.\n\n>> +[[cover-letter]]\n>> +=== Cover Letter\n>> +\n>> +The purpose of your cover letter is to sell your changes, explain what\n>> +they are about, and get your target audience interested enough to read\n>> +the patches.\n>> +\n>> +. Make sure your target audience can understand what the patches are\n>> + about and why they are needed without prior context.\n>> +\n>> +. For a second or subsequent iteration of the same topic, make sure\n>> + people who missed the earlier discussion can still understand what\n>> + the patches are about, so they can judge if the topic is worth their\n>> + time to read and comment on.\n>> +\n>> +. To help those who are familiar with earlier iterations, give a\n>> + summary of changes since the previous rounds.\n>\n> We might also recommend to include a range-diff in subsequent\n> iterations. That being said though, I just sent a small series to the\n> mailing list that recommends using b4, and there it get this for free.\n> So no idea whether it's still worth it to then cover this here\n> explicitly.\n\nI think these are orthogonal. What b4 helps you with is the shape\nof the letter, how it looks like. This update is about the contents\nin the letter, what you convey to your readers.\n\nOf course, \"format-patch --cover-letter\" also lets you do range-diff\nor interdiff, so they come for free. But the above description is\nnot tied to any particular tool to prepare your cover letter.\n\n"},{"id":"544513","messageId":"xmqqa4tdvyzv.fsf@gitster.g","threadId":"65735","inReplyTo":"fd588cff-be2b-4422-9c01-cef06b2ea5fd@gmail.com","subject":"Re: [PATCH 2/2] SubmittingPatches: describe cover letter","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-02T13:43:48Z","receivedAt":"2026-06-02T13:43:50Z","isPatch":true,"body":"Derrick Stolee writes:\n\n>> +. Make sure your target audience can understand what the patches are\n>> + about and why they are needed without prior context.\n>\n> The thing that I like to say about the cover letter is that this is\n> your opportunity to communicate why the value of your change is worth\n> the risk of regressions and the cost of maintenance. Perhaps:\n>\n> . Every code change comes with risk of regression and maintenance cost.\n> The cover letter should clearly communicate why the value of your\n> proposed change is worth applying. You can also describe how the risk\n> is reduced by the design choices you made while writing the patches.\n>\n> Or something similar may be helpful? I may just be over explaining.\n\nYeah, it may be a bit on the heavy side, but complements what I\nwanted to achieve with this update very well. I wanted to encourage\nwriting for wider audience, without leaving those \"not in the know\"\nbehind. What you wrote above is more about what to write, which is\nvery much appreciated. I think it fits well as the 0th item before\nthe three-bullet list.\n\n>> +. For a second or subsequent iteration of the same topic, make sure\n>> + people who missed the earlier discussion can still understand what\n>> + the patches are about, so they can judge if the topic is worth their\n>> + time to read and comment on.\n>> +\n>> +. To help those who are familiar with earlier iterations, give a\n>> + summary of changes since the previous rounds.\n>\n> I find these updates to be particularly helpful, even for GitGitGadget\n> PRs that include a range-diff automatically. It's good to double-check\n> the human description of the update against the computed diff.\n\nOh, absolutely.\n\nA GitGitGadget generated cover letter that lack any human input but\njust range-diff dump is often very hard to read, and the receiving\nend is better off pretending there was no useful information in the\ncover letter. \"git diff @{-1}...\" after applying the patches to the\nsame base is sadly a lot easier to read than \"git range-diff @{-1}...\"\nfor many series.\n"},{"id":"544518","messageId":"CAP8UFD0ij4BTVTie1dXwTC8M_9gAvroXebFLmQuY7eUCgHrJhA@mail.gmail.com","threadId":"65735","inReplyTo":"20260602090808.87837-2-gitster@pobox.com","subject":"Re: [PATCH 1/2] SubmittingPatches: separate typofixes section","fromName":"Christian Couder","fromEmail":"christian.couder@gmail.com","sentAt":"2026-06-02T14:24:39Z","receivedAt":"2026-06-02T14:24:53Z","isPatch":true,"body":"On Tue, Jun 2, 2026 at 11:13 AM Junio C Hamano wrote:\n>\n> The existing text said something about tests (with [[tests]] to make\n> it easier to refer to it from elsewhere) and then flowed into a\n> different topic of typofixes, but it was unclear where the latter\n> started. Add a similar [[typofies]] marker to the document.\n\ns/typofies/typofixes/\n\nThanks.\n"},{"id":"544519","messageId":"xmqqbjdtuidp.fsf@gitster.g","threadId":"65735","inReplyTo":"CAP8UFD0ij4BTVTie1dXwTC8M_9gAvroXebFLmQuY7eUCgHrJhA@mail.gmail.com","subject":"Re: [PATCH 1/2] SubmittingPatches: separate typofixes section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-02T14:28:02Z","receivedAt":"2026-06-02T14:28:04Z","isPatch":true,"body":"Christian Couder writes:\n\n> On Tue, Jun 2, 2026 at 11:13 AM Junio C Hamano wrote:\n>>\n>> The existing text said something about tests (with [[tests]] to make\n>> it easier to refer to it from elsewhere) and then flowed into a\n>> different topic of typofixes, but it was unclear where the latter\n>> started. Add a similar [[typofies]] marker to the document.\n>\n> s/typofies/typofixes/\n>\n> Thanks.\n\nThanks. It is amusing to see I cannot say typofixes when I talk\nabout them ;-)\n"},{"id":"544520","messageId":"20260602144304.3341000-1-gitster@pobox.com","threadId":"65735","inReplyTo":"20260602090808.87837-1-gitster@pobox.com","subject":"[PATCH v2 0/2] Small updates to SubmittingPatches","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-02T14:43:02Z","receivedAt":"2026-06-02T14:43:07Z","isPatch":true,"body":"Recently I gave some advice on how a cover letter should\ntry to sell the idea to widest possible audience, and then\nI realized that we do not seem to teach how in our guides.\n\nHere is a small series to do so.\n\nIn this round, a few typos have been corrected, and improvements are\nmade thanks to help from Christian, Stolee, and Patrick.\n\n 1/2: SubmittingPatches: separate typofixes section\n 2/2: SubmittingPatches: describe cover letter\n\n Documentation/SubmittingPatches | 25 +++++++++++++++++++++++++\n 1 file changed, 25 insertions(+)\n\n-- \n2.54.0-591-g9032776dcc\n\n"},{"id":"544521","messageId":"20260602144304.3341000-2-gitster@pobox.com","threadId":"65735","inReplyTo":"20260602144304.3341000-1-gitster@pobox.com","subject":"[PATCH v2 1/2] SubmittingPatches: separate typofixes section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-02T14:43:03Z","receivedAt":"2026-06-02T14:43:09Z","isPatch":true,"body":"The existing text said something about tests (with [[tests]] to make\nit easier to refer to it from elsewhere) and then flowed into a\ndifferent topic of typofixes, but it was unclear where the latter\nstarted. Add a similar [[typofixes]] marker to the document.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/SubmittingPatches | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex d570184ec8..dec8aea4cb 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -237,6 +237,7 @@ Do not forget to update the documentation to describe the updated\n behavior and make sure that the resulting documentation set formats\n well (try the Documentation/doc-diff script).\n \n+[[typofixes]]\n We currently have a liberal mixture of US and UK English norms for\n spelling and grammar, which is somewhat unfortunate. A huge patch that\n touches the files all over the place only to correct the inconsistency\n-- \n2.54.0-591-g9032776dcc\n\n"},{"id":"544522","messageId":"20260602144304.3341000-3-gitster@pobox.com","threadId":"65735","inReplyTo":"20260602144304.3341000-1-gitster@pobox.com","subject":"[PATCH v2 2/2] SubmittingPatches: describe cover letter","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-02T14:43:04Z","receivedAt":"2026-06-02T14:43:10Z","isPatch":true,"body":"We talk about how a commit log message should look like, but do not\ngive advice on writing the cover letter to sell a series to the\nwidest possible audience.\n\nHelped-by: Patrick Steinhardt \nHelped-by: Derrick Stolee \nSigned-off-by: Junio C Hamano \n---\n Documentation/SubmittingPatches | 24 ++++++++++++++++++++++++\n 1 file changed, 24 insertions(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex dec8aea4cb..df9f722bfe 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -472,6 +472,30 @@ highlighted above.\n Only capitalize the very first letter of the trailer, i.e. favor\n \"Signed-off-by\" over \"Signed-Off-By\" and \"Acked-by:\" over \"Acked-By\".\n \n+[[cover-letter]]\n+=== Cover Letter\n+\n+The purpose of your cover letter is to sell your changes, explain what\n+they are about, and get your target audience interested enough to read\n+the patches.\n+\n+. Every code change comes with risk of regression and maintenance cost.\n+ The cover letter should clearly communicate why the value of your\n+ proposed change is worth applying. You can also describe how the risk\n+ is reduced by the design choices you made while writing the patches.\n+\n+. Make sure your target audience can understand what the patches are\n+ about and why they are needed without prior context.\n+\n+. For a second or subsequent iteration of the same topic, make sure\n+ people who missed the earlier discussion can still understand what\n+ the patches are about, so they can judge if the topic is worth their\n+ time to read and comment on.\n+\n+. To help those who are familiar with earlier iterations, give a\n+ summary of changes since the previous rounds.\n+\n+\n [[ai]]\n === Use of Artificial Intelligence (AI)\n \n-- \n2.54.0-591-g9032776dcc\n\n"},{"id":"544523","messageId":"c64bb761-a412-4ec5-a1b5-30f0893a3d1f@app.fastmail.com","threadId":"65735","inReplyTo":"20260602090808.87837-2-gitster@pobox.com","subject":"Re: [PATCH 1/2] SubmittingPatches: separate typofixes section","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-02T14:46:05Z","receivedAt":"2026-06-02T14:46:27Z","isPatch":true,"body":"On Tue, Jun 2, 2026, at 11:08, Junio C Hamano wrote:\n> The existing text said something about tests (with [[tests]] to make\n> it easier to refer to it from elsewhere) and then flowed into a\n> different topic of typofixes, but it was unclear where the latter\n> started. Add a similar [[typofies]] marker to the document.\n>\n> Signed-off-by: Junio C Hamano \n> ---\n\nImperative mood?\n"},{"id":"544527","messageId":"CAP8UFD1Kp_bex9E4t_1Jj9bnKeUn4=fOgEHemGyqJNfWydpEYA@mail.gmail.com","threadId":"65735","inReplyTo":"xmqqbjdtuidp.fsf@gitster.g","subject":"Re: [PATCH 1/2] SubmittingPatches: separate typofixes section","fromName":"Christian Couder","fromEmail":"christian.couder@gmail.com","sentAt":"2026-06-02T15:16:03Z","receivedAt":"2026-06-02T15:16:18Z","isPatch":true,"body":"On Tue, Jun 2, 2026 at 4:28 PM Junio C Hamano wrote:\n>\n> Christian Couder writes:\n\n> > s/typofies/typofixes/\n> >\n> > Thanks.\n>\n> Thanks. It is amusing to see I cannot say typofixes when I talk\n> about them ;-)\n\nI wondered a bit if it was a case of satiric or ironical misspelling,\nbut it looks like in English the usual words for them are \"grammer\"\nand \"speling\", like in:\n\n\"I am an expert in English grammer and speling.\" ;-)\n"},{"id":"544529","messageId":"c54f3571-ff7b-4caa-b75d-a739ed87ec9d@gmail.com","threadId":"65735","inReplyTo":"20260602144304.3341000-1-gitster@pobox.com","subject":"Re: [PATCH v2 0/2] Small updates to SubmittingPatches","fromName":"Derrick Stolee","fromEmail":"stolee@gmail.com","sentAt":"2026-06-02T15:24:48Z","receivedAt":"2026-06-02T15:24:49Z","isPatch":true,"body":"On 6/2/2026 10:43 AM, Junio C Hamano wrote:\n> Recently I gave some advice on how a cover letter should\n> try to sell the idea to widest possible audience, and then\n> I realized that we do not seem to teach how in our guides.\n> \n> Here is a small series to do so.\n> \n> In this round, a few typos have been corrected, and improvements are\n> made thanks to help from Christian, Stolee, and Patrick.\nThis version LGTM.\n\nThanks,\n-Stolee\n\n"},{"id":"544672","messageId":"aiEgUdnL8dkszKFn@pks.im","threadId":"65735","inReplyTo":"c54f3571-ff7b-4caa-b75d-a739ed87ec9d@gmail.com","subject":"Re: [PATCH v2 0/2] Small updates to SubmittingPatches","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-04T06:50:57Z","receivedAt":"2026-06-04T06:51:03Z","isPatch":true,"body":"On Tue, Jun 02, 2026 at 11:24:48AM -0400, Derrick Stolee wrote:\n> On 6/2/2026 10:43 AM, Junio C Hamano wrote:\n> > Recently I gave some advice on how a cover letter should\n> > try to sell the idea to widest possible audience, and then\n> > I realized that we do not seem to teach how in our guides.\n> > \n> > Here is a small series to do so.\n> > \n> > In this round, a few typos have been corrected, and improvements are\n> > made thanks to help from Christian, Stolee, and Patrick.\n> This version LGTM.\n\nAgreed, I'm happy with this version.\n\nPatrick\n"}]}