{"thread":{"id":"65141","subject":"[PATCH] Documentation: extend guidance for submitting patches","startedAt":"2026-03-05T19:38:48Z","lastAt":"2026-03-06T12:58:56Z","messageCount":9,"participants":["Justin Tobler","Junio C Hamano","Kristoffer Haugsbakk","brian m. carlson"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"537993","messageId":"20260305193836.973122-1-jltobler@gmail.com","threadId":"65141","inReplyTo":null,"subject":"[PATCH] Documentation: extend guidance for submitting patches","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2026-03-05T19:38:36Z","receivedAt":"2026-03-05T19:38:48Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"Before submitting patches on the mailing list, it is often a good idea\nto check for previous related discussions or if similar work is already\nin progress. This enables better coordination amongst contributors and\ncould avoid duplicating work.\n\nAdditionally, it is often recommended to give reviewers some time to\nreply to a patch series before sending new versions. This helps collect\nbroader feedback and reduces unnecessary churn from rapid rerolls.\n\nDocument this guidance in \"Documentation/SubmittingPatches\" accordingly.\n\nSigned-off-by: Justin Tobler \n---\n Documentation/SubmittingPatches | 13 +++++++++++++\n 1 file changed, 13 insertions(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex e270ccbe85..5acd692ad7 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -38,10 +38,23 @@ they have no obligation to help you (i.e. you ask them for help,\n you don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would\n help you find out who they are.\n \n+It is also a good idea to check whether your topic has been discussed\n+previously on the mailing list, or whether similar work is already in\n+progress. Prior discussions may contain useful context, design\n+considerations, or earlier attempts at solving the same problem. Being\n+aware of such discussions can help you avoid duplicating work and may\n+allow you to coordinate with other contributors working in the same\n+area.\n+\n . You get comments and suggestions for improvements. You may even get\n them in an \"on top of your change\" patch form. You are expected to\n respond to them with \"Reply-All\" on the mailing list, while taking\n them into account while preparing an updated set of patches.\n++\n+It is often beneficial to allow some time for reviewers to provide\n+feedback before sending a new version, rather than sending an updated\n+series immediately after receiving a review. This helps collect broader\n+input and avoids unnecessary churn from many rapid iterations.\n \n . Polish, refine, and re-send your patches to the list and to the people\n who spent their time to improve your patch. Go back to step (2).\n\nbase-commit: 628a66ccf68d141d57d06e100c3514a54b31d6b7\n-- \n2.53.0.381.g628a66ccf6\n\n"},{"id":"537995","messageId":"xmqqikba2evz.fsf@gitster.g","threadId":"65141","inReplyTo":"20260305193836.973122-1-jltobler@gmail.com","subject":"Re: [PATCH] Documentation: extend guidance for submitting patches","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-03-05T20:35:44Z","receivedAt":"2026-03-05T20:35:47Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Justin Tobler writes:\n\n> Before submitting patches on the mailing list, it is often a good idea\n> to check for previous related discussions or if similar work is already\n> in progress. This enables better coordination amongst contributors and\n> could avoid duplicating work.\n>\n> Additionally, it is often recommended to give reviewers some time to\n> reply to a patch series before sending new versions. This helps collect\n> broader feedback and reduces unnecessary churn from rapid rerolls.\n>\n> Document this guidance in \"Documentation/SubmittingPatches\" accordingly.\n>\n> Signed-off-by: Justin Tobler \n> ---\n> Documentation/SubmittingPatches | 13 +++++++++++++\n> 1 file changed, 13 insertions(+)\n\nWhat's written in these two new paragraphs are all agreeable, but is\nthe first addition in the right place with correct mark-up?\n\nThis whole section is a sequence of bullet points that shows \"a\ntypical life cycle of a patch series\". The first bullet point\nstarts with \"You come up with an itch.\" and the second one is \"You\nsend the patches\", whose end part is what we see in the pre-context\nof the patch, ending with \"help you find out who they are.\"\n\nIf the new paragraph is meant as yet another paragraph to elaborate\non that second bullet point, wouldn't we need that \"a line with only\na single '+' on it\" before it, instead of a blank line, and the last\nline of the first new paragraph should not be such a \"single '+'\"\nline but a plain vanilla blank line?\n\n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> index e270ccbe85..5acd692ad7 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -38,10 +38,23 @@ they have no obligation to help you (i.e. you ask them for help,\n> you don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would\n> help you find out who they are.\n> \n> +It is also a good idea to check whether your topic has been discussed\n> +previously on the mailing list, or whether similar work is already in\n> +progress. Prior discussions may contain useful context, design\n> +considerations, or earlier attempts at solving the same problem. Being\n> +aware of such discussions can help you avoid duplicating work and may\n> +allow you to coordinate with other contributors working in the same\n> +area.\n> +\n> . You get comments and suggestions for improvements. You may even get\n> them in an \"on top of your change\" patch form. You are expected to\n> respond to them with \"Reply-All\" on the mailing list, while taking\n> them into account while preparing an updated set of patches.\n> ++\n> +It is often beneficial to allow some time for reviewers to provide\n> +feedback before sending a new version, rather than sending an updated\n> +series immediately after receiving a review. This helps collect broader\n> +input and avoids unnecessary churn from many rapid iterations.\n> \n> . Polish, refine, and re-send your patches to the list and to the people\n> who spent their time to improve your patch. Go back to step (2).\n>\n> base-commit: 628a66ccf68d141d57d06e100c3514a54b31d6b7\n"},{"id":"537999","messageId":"aan0FUBE1LwrFc4y@denethor","threadId":"65141","inReplyTo":"xmqqikba2evz.fsf@gitster.g","subject":"Re: [PATCH] Documentation: extend guidance for submitting patches","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2026-03-05T21:27:34Z","receivedAt":"2026-03-05T21:27:38Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"On 26/03/05 12:35PM, Junio C Hamano wrote:\n> Justin Tobler writes:\n> \n> > Before submitting patches on the mailing list, it is often a good idea\n> > to check for previous related discussions or if similar work is already\n> > in progress. This enables better coordination amongst contributors and\n> > could avoid duplicating work.\n> >\n> > Additionally, it is often recommended to give reviewers some time to\n> > reply to a patch series before sending new versions. This helps collect\n> > broader feedback and reduces unnecessary churn from rapid rerolls.\n> >\n> > Document this guidance in \"Documentation/SubmittingPatches\" accordingly.\n> >\n> > Signed-off-by: Justin Tobler \n> > ---\n> > Documentation/SubmittingPatches | 13 +++++++++++++\n> > 1 file changed, 13 insertions(+)\n> \n> What's written in these two new paragraphs are all agreeable, but is\n> the first addition in the right place with correct mark-up?\n> \n> This whole section is a sequence of bullet points that shows \"a\n> typical life cycle of a patch series\". The first bullet point\n> starts with \"You come up with an itch.\" and the second one is \"You\n> send the patches\", whose end part is what we see in the pre-context\n> of the patch, ending with \"help you find out who they are.\"\n> \n> If the new paragraph is meant as yet another paragraph to elaborate\n> on that second bullet point, wouldn't we need that \"a line with only\n> a single '+' on it\" before it, instead of a blank line, and the last\n> line of the first new paragraph should not be such a \"single '+'\"\n> line but a plain vanilla blank line?\n\nAh yes apologies. The first addition to start with a line prefixed with\n'+' intead of a blank line. I do believe it does already end with a\nblank line though. I'll correct in the next version.\n\nThanks,\n-Justin\n"},{"id":"538000","messageId":"xmqqzf4m0xju.fsf@gitster.g","threadId":"65141","inReplyTo":"aan0FUBE1LwrFc4y@denethor","subject":"Re: [PATCH] Documentation: extend guidance for submitting patches","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-03-05T21:35:33Z","receivedAt":"2026-03-05T21:35:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Justin Tobler writes:\n\n> Ah yes apologies. The first addition to start with a line prefixed with\n> '+' intead of a blank line. I do believe it does already end with a\n> blank line though. I'll correct in the next version.\n\nI have the following queued on top. If there is nothing else, I\ncan just squash it in.\n\nSubject: [PATCH] SQUASH??? mark-up fix\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/SubmittingPatches | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 5acd692ad7..359f5fb74e 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -37,7 +37,7 @@ most likely to be knowledgeable enough to help you, but\n they have no obligation to help you (i.e. you ask them for help,\n you don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would\n help you find out who they are.\n-\n++\n It is also a good idea to check whether your topic has been discussed\n previously on the mailing list, or whether similar work is already in\n progress. Prior discussions may contain useful context, design\n-- \n2.53.0-621-g5d45fffb26\n\n"},{"id":"538001","messageId":"aan4xVGaehnXB1Hd@denethor","threadId":"65141","inReplyTo":"xmqqzf4m0xju.fsf@gitster.g","subject":"Re: [PATCH] Documentation: extend guidance for submitting patches","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2026-03-05T21:43:38Z","receivedAt":"2026-03-05T21:43:40Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"On 26/03/05 01:35PM, Junio C Hamano wrote:\n> Justin Tobler writes:\n> \n> > Ah yes apologies. The first addition to start with a line prefixed with\n> > '+' intead of a blank line. I do believe it does already end with a\n> > blank line though. I'll correct in the next version.\n> \n> I have the following queued on top. If there is nothing else, I\n> can just squash it in.\n\nPerfect. Thanks for fixing. :)\n\n-Justin\n"},{"id":"538004","messageId":"be9cbba2-883a-4ef8-838e-0941b75eee6f@app.fastmail.com","threadId":"65141","inReplyTo":"20260305193836.973122-1-jltobler@gmail.com","subject":"Re: [PATCH] Documentation: extend guidance for submitting patches","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-03-05T22:27:28Z","receivedAt":"2026-03-05T22:27:50Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Thu, Mar 5, 2026, at 20:38, Justin Tobler wrote:\n> Before submitting patches on the mailing list, it is often a good idea\n> to check for previous related discussions or if similar work is already\n> in progress. This enables better coordination amongst contributors and\n> could avoid duplicating work.\n>\n> Additionally, it is often recommended to give reviewers some time to\n> reply to a patch series before sending new versions. This helps collect\n> broader feedback and reduces unnecessary churn from rapid rerolls.\n>\n> Document this guidance in \"Documentation/SubmittingPatches\" accordingly.\n>\n> Signed-off-by: Justin Tobler \n> ---\n> Documentation/SubmittingPatches | 13 +++++++++++++\n> 1 file changed, 13 insertions(+)\n>\n> diff --git a/Documentation/SubmittingPatches\n> b/Documentation/SubmittingPatches\n> index e270ccbe85..5acd692ad7 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -38,10 +38,23 @@ they have no obligation to help you (i.e. you ask\n> them for help,\n> you don't demand). +git log -p {litdd} _$area_you_are_modifying_+\n> would\n> help you find out who they are.\n>\n> +It is also a good idea to check whether your topic has been discussed\n> +previously on the mailing list,\n\nThis is at the start of the document. “The mailing list” footnote\n(git-ml) does not get mentioned until line 535.\n\nAlthough there is the initial mention of `MyFirstContribution` which\nprominently features the address at the start.\n\n> or whether similar work is already in\n> +progress. Prior discussions may contain useful context, design\n> +considerations, or earlier attempts at solving the same problem. Being\n> +aware of such discussions can help you avoid duplicating work and may\n> +allow you to coordinate with other contributors working in the same\n> +area.\n> +\n\nThis seems useful to cite. It seems less useful for people who go to the\neffort of reading this file themselves. They presumably care enough to\ntry to get the procedural steps correct. It’s difficult to imagine that\nthey either think that their idea has to be unique or that there isn’t a\nhistory.\n\n> . You get comments and suggestions for improvements. You may even get\n> them in an \"on top of your change\" patch form. You are expected to\n> respond to them with \"Reply-All\" on the mailing list, while taking\n> them into account while preparing an updated set of patches.\n> ++\n> +It is often beneficial to allow some time for reviewers to provide\n> +feedback before sending a new version, rather than sending an updated\n> +series immediately after receiving a review. This helps collect broader\n> +input and avoids unnecessary churn from many rapid iterations.\n\nThis addition makes sense including its placement.\n\n>\n> . Polish, refine, and re-send your patches to the list and to the people\n> who spent their time to improve your patch. Go back to step (2).\n>\n> base-commit: 628a66ccf68d141d57d06e100c3514a54b31d6b7\n> --\n> 2.53.0.381.g628a66ccf6\n"},{"id":"538042","messageId":"aaowCeEMjpztZpti@denethor","threadId":"65141","inReplyTo":"be9cbba2-883a-4ef8-838e-0941b75eee6f@app.fastmail.com","subject":"Re: [PATCH] Documentation: extend guidance for submitting patches","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2026-03-06T01:48:49Z","receivedAt":"2026-03-06T01:48:53Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"On 26/03/05 11:27PM, Kristoffer Haugsbakk wrote:\n> On Thu, Mar 5, 2026, at 20:38, Justin Tobler wrote:\n> > +It is also a good idea to check whether your topic has been discussed\n> > +previously on the mailing list,\n> \n> This is at the start of the document. “The mailing list” footnote\n> (git-ml) does not get mentioned until line 535.\n> \n> Although there is the initial mention of `MyFirstContribution` which\n> prominently features the address at the start.\n\nWe also mention \"the list\" several times in the surround bullet points\nprior to the footnote too. If we think it matters I can move the\nfootnote up.\n\n> > or whether similar work is already in\n> > +progress. Prior discussions may contain useful context, design\n> > +considerations, or earlier attempts at solving the same problem. Being\n> > +aware of such discussions can help you avoid duplicating work and may\n> > +allow you to coordinate with other contributors working in the same\n> > +area.\n> > +\n> \n> This seems useful to cite. It seems less useful for people who go to the\n> effort of reading this file themselves. They presumably care enough to\n> try to get the procedural steps correct. It’s difficult to imagine that\n> they either think that their idea has to be unique or that there isn’t a\n> history.\n\nYa, I agree that most folks who feel inclined to read this document\nproactively would likely also lookup previous/on-going mailing list\ndiscussions. I do think this would be useful though to include so we can\npoint contributors this direction when needed.\n\nThanks,\n-Justin\n"},{"id":"538067","messageId":"a61453ef-d3af-429e-8f2e-5a9ae3d47df7@app.fastmail.com","threadId":"65141","inReplyTo":"aaowCeEMjpztZpti@denethor","subject":"Re: [PATCH] Documentation: extend guidance for submitting patches","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-03-06T10:56:08Z","receivedAt":"2026-03-06T10:56:30Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Fri, Mar 6, 2026, at 02:48, Justin Tobler wrote:\n> On 26/03/05 11:27PM, Kristoffer Haugsbakk wrote:\n>> On Thu, Mar 5, 2026, at 20:38, Justin Tobler wrote:\n>> > +It is also a good idea to check whether your topic has been discussed\n>> > +previously on the mailing list,\n>>\n>> This is at the start of the document. “The mailing list” footnote\n>> (git-ml) does not get mentioned until line 535.\n>>\n>> Although there is the initial mention of `MyFirstContribution` which\n>> prominently features the address at the start.\n>\n> We also mention \"the list\" several times in the surround bullet points\n> prior to the footnote too. If we think it matters I can move the\n> footnote up.\n\nYeah that can be solved separately also. :)\n\n>> > or whether similar work is already in\n>> > +progress. Prior discussions may contain useful context, design\n>> > +considerations, or earlier attempts at solving the same problem. Being\n>> > +aware of such discussions can help you avoid duplicating work and may\n>> > +allow you to coordinate with other contributors working in the same\n>> > +area.\n>> > +\n>>\n>> This seems useful to cite. It seems less useful for people who go to the\n>> effort of reading this file themselves. They presumably care enough to\n>> try to get the procedural steps correct. It’s difficult to imagine that\n>> they either think that their idea has to be unique or that there isn’t a\n>> history.\n>\n> Ya, I agree that most folks who feel inclined to read this document\n> proactively would likely also lookup previous/on-going mailing list\n> discussions. I do think this would be useful though to include so we can\n> point contributors this direction when needed.\n\nThat sounds good to me.\n"},{"id":"538071","messageId":"aarPjlYv0H10rNKJ@fruit.crustytoothpaste.net","threadId":"65141","inReplyTo":"20260305193836.973122-1-jltobler@gmail.com","subject":"Re: [PATCH] Documentation: extend guidance for submitting patches","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2026-03-06T12:58:54Z","receivedAt":"2026-03-06T12:58:56Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2026-03-05 at 19:38:36, Justin Tobler wrote:\n> +It is also a good idea to check whether your topic has been discussed\n> +previously on the mailing list, or whether similar work is already in\n> +progress. Prior discussions may contain useful context, design\n> +considerations, or earlier attempts at solving the same problem. Being\n> +aware of such discussions can help you avoid duplicating work and may\n> +allow you to coordinate with other contributors working in the same\n> +area.\n\nThis seems reasonable. We've had cases of patch series that have\nstalled due to a minor issue and someone wanting to send a patch may\nfind that they really could fix that minor issue on top of the existing\npatch and have their problem solved. Or at least, they might be\ninclined to not get stuck in the same way.\n\nI try to do this anyway, but it's much easier on forge-style systems\nthan it is on a mailing list, so mentioning it may help refresh people's\nmemories.\n\nYou could, if you wanted to, link to `{gitml}` after the phrase “the\nmailing list,” which might help folks find the right location. Or you\ncould link to the https://lore.kernel.org/git/ archives instead via a\nfootnote.\n\n> +It is often beneficial to allow some time for reviewers to provide\n> +feedback before sending a new version, rather than sending an updated\n> +series immediately after receiving a review. This helps collect broader\n> +input and avoids unnecessary churn from many rapid iterations.\n\nI think this is a good idea, too.\n-- \nbrian m. carlson (they/them)\nToronto, Ontario, CA\n"}]}