Re: [PATCH 0/3] format-patch: --interiff/--range-diff tweaks

[Eric Sunshine <sunshine@sunshineco.com>]

On Tue, Sep 8, 2020 at 6:11 PM Junio C Hamano <gitster@pobox.com> wrote:
> Eric Sunshine <sunshine@sunshineco.com> writes:
> > This series addresses a few comments[2,3,4,5] which cropped up during
> > review of the series which added --interdiff and --range-diff options to
> > git-format-patch[1]. That series made it into 'next' before I could address
> > the comments, so these patches (based upon 'master') make minor tweaks
> > "incrementally" (over 2 years late).
>
> The last step subtly changes the behaviour, if I am reading its
> description correctly.  Does it deserve a documentation update, or
> are we just making the code behave "better" but still within the
> boundary of how it is documented to work, hence no need to update
> the doc (but deserves an advertisement in the release notes)?

I honestly don't have an answer because I have trouble reasoning about
these cases (perhaps due to unclear mental model). That's part of the
reason why this patch series took so long. The first two patches were
ready in September 2018, but I kept putting off the third one because
I was having trouble understanding your suggested changes. It only
started to click the other day when I sat down and really studied your
proposal for a long time. Attempting to write a meaningful commit
message, rather than a hand-wavy one, forced me to think about it even
more critically, which helped (perhaps even more than the code itself)
to better understand it.

I wouldn't be opposed to dropping the last patch, however, with
whatever understanding I gained, I do agree that the way you suggested
coding it does make more sense and is more intuitive. But that doesn't
mean that it is sufficiently concrete in my brain to say whether a
documentation update is warranted and, if so, exactly how to
articulate such an update.