Re: [PATCH] MyFirstContribution: Document --range-diff option when writing v2

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Sep 14, 2021, 03:46 UTC
Message-ID: <CAPig+cSHSSuE6ovPN+XVRDhNU8WD+XzuH0gLzupNZiN1QLGz9A@mail.gmail.com>
In-Reply-To: <02e15e8d-6923-9f21-8eeb-592eb0c9588b@gmail.com>

On Mon, Sep 13, 2021 at 10:43 PM Bagas Sanjaya <bagasdotme@gmail.com> wrote:

Show 11 quoted lines

> On 14/09/21 02.48, Glen Choo wrote:
> > In the "Sending V2" section, readers are directed to create v2 patches
> > without using --range-diff. However, it is custom to include a range
> > diff against the v1 patches as a reviewer aid.
> >
> > Update the "Sending V2" section to include the --range-diff option. Also
> > include some explanation for -v2 and --range-diff to help the reader
> > understand the importance.
>
> I think plain "Changes since v1 [link]" is sufficient if you can
> describe such changes well without resorting to range-diff.

Not so. Anyone who does any serious amount of review on this project finds it tremendously helpful to have both a prose description of the changes ("Changes since v1..." plus a link to the previous submission) and a mechanical range-diff or interdiff. A range-diff (or interdiff) is especially important to provide reviewers with context which they might have forgotten since the previous version of a patch series was posted, which can matter since it's so easy to forget specifics even about one's own review if enough time has passed or if reviewing a large number of unrelated submissions. A range-diff or interdiff also helps a reviewer determine at-a-glance whether or not earlier review comments have been addressed without having to laboriously re-read each and every patch.