[PATCH] SubmittingPatches: address design critiques

[PATCH] SubmittingPatches: address design critiques

[Junio C Hamano]

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>
---
 Documentation/SubmittingPatches | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 176567738d..bfe3745a54 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.
 +
+You would want to be particularly mindful of critiques regarding the
+high-level design or viability of your proposal (e.g., questioning
+whether the feature is worth implementing, or if the chosen approach
+is appropriate).  You want to defend your design decisions on the list
+first, because you do not want to spend too much effort in the
+implementation if the design is not yet solid.
++
+Also, make sure that any new version is accompanied by a much clearer
+explanation and justification (in the cover letter, your responses,
+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 that fail to address fundamental design critiques without
+resolution 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
@@ -322,6 +337,10 @@ The body should provide a meaningful commit message, which:
 
 . alternate solutions considered but discarded, if any.
 
+. 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-92-ge545aa9d3e

[PATCH v2] SubmittingPatches: address design critiques

[Junio C Hamano]

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>
---

 * Rephrased the instruction in the first hunk somewhat to be a bit
   more explicit, and added a missing verb to the second hunk.

 Documentation/SubmittingPatches | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index f042bb5aaf..bbe759f3d9 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.
 +
+You should be particularly mindful of critiques regarding the
+high-level design or viability of your proposal (e.g., questioning
+whether the feature is worth implementing, or if the chosen approach
+is appropriate).  Defend your design decisions on the list first, to
+avoid wasting effort on an implementation whose design is not yet
+solid.
++
+Make sure that any new version is accompanied by a much clearer
+explanation and justification (in the cover letter, your responses,
+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 that fail to address fundamental design critiques without
+resolution 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",

Range-diff against v1:
1:  eb5f96ab04 ! 1:  aecdcf0bda SubmittingPatches: address design critiques
    @@ Documentation/SubmittingPatches: area.
        respond to them with "Reply-All" on the mailing list, while taking
        them into account while preparing an updated set of patches.
      +
    -+You would want to be particularly mindful of critiques regarding the
    ++You should be particularly mindful of critiques regarding the
     +high-level design or viability of your proposal (e.g., questioning
     +whether the feature is worth implementing, or if the chosen approach
    -+is appropriate).  You want to defend your design decisions on the list
    -+first, because you do not want to spend too much effort in the
    -+implementation if the design is not yet solid.
    ++is appropriate).  Defend your design decisions on the list first, to
    ++avoid wasting effort on an implementation whose design is not yet
    ++solid.
     ++
    -+Also, make sure that any new version is accompanied by a much clearer
    ++Make sure that any new version is accompanied by a much clearer
     +explanation and justification (in the cover letter, your responses,
     +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".
    @@ Documentation/SubmittingPatches: The body should provide a meaningful commit mes
      
      . alternate solutions considered but discarded, if any.
      
    -+. the resolution of design or viability concerns raised by the
    ++. 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.
     +
-- 
2.55.0-rc1-93-ge727df1850