From: Junio C Hamano Date: Wed, 24 Jun 2026 20:21:12 +0000 (-0700) Subject: Merge branch 'wy/doc-clarify-review-replies' into jch X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=000b5fbb721f12aef38208e06751cf0be794d0dd;p=thirdparty%2Fgit.git Merge branch 'wy/doc-clarify-review-replies' into jch Documentation on community contribution guidelines has been updated to encourage replying to review comments before rerolling, and to advise a default limit of at most one reroll per day to give reviewers across different time zones enough time to participate. * wy/doc-clarify-review-replies: doc: advise batching patch rerolls doc: encourage review replies before rerolling --- 000b5fbb721f12aef38208e06751cf0be794d0dd diff --cc Documentation/SubmittingPatches index bec884fa46,d89efe0707..d2d82eb543 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@@ -48,25 -48,13 +48,29 @@@ area . You get comments and suggestions for improvements. You may even get them in an "on top of your change" patch form. You are expected to - respond to them with "Reply-All" on the mailing list, while taking - them into account while preparing an updated set of patches. + respond to them with "Reply-All" on the mailing list, instead of + letting an updated patch series be your only response. Tell + reviewers which suggestions you plan to use, which ones you disagree + with, and when a comment leads you to consider a different approach. + Use these replies and any follow-up discussion as input when + 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 and work with reviewers and +other members to improve the design before revising the implementation. +This will 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 @@@ -661,10 -625,13 +673,13 @@@ grouped into their own e-mail thread t series. To that end, send them as replies to either an additional "cover letter" message (see below), the first patch, or the respective preceding patch. Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on - how to submit updated versions of a patch series. + how to submit updated versions of a patch series. Before sending another + version, make sure you have answered meaningful review comments in the existing + discussion. Also give reviewers enough time to comment before sending another + version. If your log message (including your name on the -`Signed-off-by` trailer) is not writable in ASCII, make sure that +`Signed-off-by:` trailer) is not writable in ASCII, make sure that you send off a message in the correct encoding. WARNING: Be wary of your MUAs word-wrap