Re: [RFC PATCH 1/2] doc: encourage review replies before rerolling

> Review feedback should not be answered only by sending a new patch
> version. Encourage contributors to discuss their planned response in the
> mailing-list thread before rerolling.
> 
> This makes the author's reasoning explicit before the next version is
> prepared, instead of forcing reviewers to infer it from the rerolled
> patches.

> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
> index 0e2a9313ce..59891e3c14 100644
> --- a/Documentation/MyFirstContribution.adoc
> +++ b/Documentation/MyFirstContribution.adoc
> @@ -1423,11 +1423,13 @@ fewer mistakes were the only one they would need to review.
>  After a few days, you will hopefully receive a reply to your patchset with some
>  comments. Woohoo! Now you can get back to work.
>  
> -It's good manners to reply to each comment, notifying the reviewer that you have
> -made the change suggested, feel the original is better, or that the comment
> -inspired you to do something a new way which is superior to both the original
> -and the suggested change. This way reviewers don't need to inspect your v2 to
> -figure out whether you implemented their comment or not.
> +It's good manners to reply to each comment in the mailing list discussion
> +instead of letting the next version of your patch be your only response. Tell
> +the reviewer whether you plan to make the suggested change, keep the original,
> +or pursue a different approach. This way reviewers can respond to your reasoning
> +before you spend time preparing a version they may not agree with, and later do
> +not need to inspect your v2 to figure out whether you implemented their comment
> +or not.
>  
>  Reviewers may ask you about what you wrote in the patchset, either in
>  the proposed commit log message or in the changes themselves.  You

> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 6b83b6c89e..d8ad7fb73e 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -48,8 +48,12 @@ 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.

> @@ -639,7 +643,9 @@ grouped into their own e-mail thread to help readers find all parts of the
>  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.