SubmittingPatches: address design critiques
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>
Junio C Hamano committed
Jun 20, 2026 at 16:43 UTC
5fe19d285c832b12de1479c78231d53842b44583
1 file changed
+20
Documentation/SubmittingPatches
+20
@@ -51,6 +51,22 @@ area.
51
respond to them with "Reply-All" on the mailing list, while taking
52
them into account while preparing an updated set of patches.
53
+
54
+Be particularly mindful of critiques regarding the high-level design
55
+or viability of your proposal (e.g., questioning if the feature is
56
+worth implementing, or if the chosen approach is appropriate). Defend
57
+your design decisions on the list first and work with reviewers and
58
+other members to improve the design before revising the implementation.
59
+This will avoid wasting effort on an implementation before its design is
60
+solid.
61
++
62
+Make sure that any new version explains and justifies those design
63
+decisions more clearly, in the cover letter and in the revised commit
64
+messages. Aim to make the reviewers say "it is now clear why we may
65
+want to do this with the updated version".
66
++
67
+Topics with unresolved fundamental design critiques will not be
68
+considered ready for merging.
69
++
70
It is often beneficial to allow some time for reviewers to provide
71
feedback before sending a new version, rather than sending an updated
72
series immediately after receiving a review. This helps collect broader
@@ -323,6 +339,10 @@ The body should provide a meaningful commit message, which:
339
340
. alternate solutions considered but discarded, if any.
341
342
+. records the resolution of design or viability concerns raised by the
343
+ community during the review, if any, ensuring the historical record
344
+ explains why the chosen approach was accepted over alternatives.
345
+
346
[[present-tense]]
347
The problem statement that describes the status quo is written in the
348
present tense. Write "The code does X when it is given input Y",