git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v3] SubmittingPatches: address design critiques

From
Junio C Hamano <gitster@pobox.com>
Date
Jun 19, 2026, 16:17 UTC
Message-ID
<xmqqik7eld2g.fsf_-_@gitster.g>
In-Reply-To
<xmqqpl1oteoi.fsf@gitster.g>

Contributors sometimes fail to answer fundamental design or viability comments from reviewers and submit subsequent rounds without addressing them. When design decisions are resolved on the mailing list, the final justification should be recorded in the commit messages.

Instruct authors to be particularly mindful of critiques regarding high-level design or viability, to defend their choices on the list, and to accompany new iterations with clearer explanations in the cover letter, responses, and revised commit messages. Also instruct them to explicitly document the resolution of these concerns in the commit message body to keep the historical record complete.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 * Updated a bit after reading comments by Kichael and Kristoffer
 Documentation/SubmittingPatches | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index f042bb5aaf..a9789e5303 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -51,6 +51,21 @@ area.
   respond to them with "Reply-All" on the mailing list, while taking
   them into account while preparing an updated set of patches.
 +
+Be particularly mindful of critiques regarding the high-level design
+or viability of your proposal (e.g., questioning if the feature is
+worth implementing, or if the chosen approach is appropriate).  Defend
+your design decisions on the list first, work with reviewers and other
+members to improve the design before revising the implementation, to
+avoid wasting effort on an implementation before its design is solid.
++
+Make sure that any new version explains and justifies those design
+decisions more clearly, in the cover letter and in the revised commit
+messages.  Aim to make the reviewers say "it is now clear why we may
+want to do this with the updated version".
++
+Topics with unresolved fundamental design critiques will not be
+considered ready for merging.
++
 It is often beneficial to allow some time for reviewers to provide
 feedback before sending a new version, rather than sending an updated
 series immediately after receiving a review. This helps collect broader
@@ -323,6 +338,10 @@ The body should provide a meaningful commit message, which:
 
 . alternate solutions considered but discarded, if any.
 
+. records the resolution of design or viability concerns raised by the
+  community during the review, if any, ensuring the historical record
+  explains why the chosen approach was accepted over alternatives.
+
 [[present-tense]]
 The problem statement that describes the status quo is written in the
 present tense.  Write "The code does X when it is given input Y",
-- 
2.55.0-rc1-129-gff98d784de
Previous: Junio C HamanoNext: Junio C Hamano
Message 5 of 8 in “SubmittingPatches: address design critiques”
  1. SubmittingPatches: address design critiquesJunio C Hamano, Jun 17, 2026
  2. SubmittingPatches: address design critiquesJunio C Hamano, Jun 18, 2026
  3. Kristoffer HaugsbakkJun 18, 2026
  4. Junio C HamanoJun 18, 2026
  5. SubmittingPatches: address design critiquesJunio C Hamano, Jun 19, 2026
  6. SubmittingPatches: address design critiquesJunio C Hamano, Jun 20, 2026
  7. Patrick SteinhardtJun 22, 2026
  8. Junio C HamanoJun 22, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.