Re: [PATCH 1/2] bisect--helper: use OPT_CMDMODE instead of OPT_BOOL

From: Christian Couder <christian.couder@gmail.com>
Date: May 4, 2016, 19:07 UTC
Message-ID: <CAP8UFD2qoCPkbDid+k6Lydh7JTM5VhQzxTSuJuRa40sw54_aZw@mail.gmail.com>
In-Reply-To: <alpine.DEB.2.20.1605041654300.9313@virtualbox>

Hi Dscho,

On Wed, May 4, 2016 at 4:56 PM, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

Show 13 quoted lines

> Hi Christian,
>
> On Wed, 4 May 2016, Christian Couder wrote:
>
>> My intent was to try to show that there is some important value to make
>> the subject close to the "low level" thing the patch actually does.
>
> I disagree. The place to describe low-level details that are not
> immediately obvious from the patch is the commit message. Way, way down on
> the bottom.
>
> The commit message should start with a subject that gives me a good clue
> why this is a good change. A low-level detail won't do that very often.

Let me give you another example.

You want to do X and you discover that you need to tweek knob foo to do X, and also that tweeking knob foo is a good thing to do in general (for example it could be a refactoring that save some lines of code). So you create a patch that tweeks knob foo and call it "prepare to do X", and then send it so that it can be merged. Then you want to do X but you are interupted by an event, for example you boss tells you to do Y instead of X right away because of an urgent business need. So you do Y instead of X. And then sometimes later (it could be weeks, months or years later), when you are finished with Y, you now want to go back to your previous work on X. At that time you discover that you need to tweek knob bar (it could be another refactoring of another part of the code), but you forgot about your previous patch that tweeked knob foo, so you call your new patch that tweeks knob bar "prepare to do X". As your previous patch that was also called "prepare to do X" has already been integrated, you now have too patches that do different things that are called the same, and you can easily mistake the first one for the second one.

If you had just called your first patch "tweek knob foo" and the second patch "tweek knob bar", it would be much clearer which patch does what.