Re: [RFC/PATCH] commit notes workflow

From: Piotr Krukowiecki <piotr.krukowiecki@gmail.com>
Date: Mar 2, 2011, 16:24 UTC
Message-ID: <AANLkTimW-Cs5LVVOL9tpFiN6JsarWVo4Kua4ky7N1HB-@mail.gmail.com>
In-Reply-To: <4D6DEB64.1080003@gmail.com>

Hi,

On Wed, Mar 2, 2011 at 8:01 AM, Chris Packham <judge.packham@gmail.com> wrote:

Show 23 quoted lines

> On 02/03/11 10:59, Jeff King wrote:
>> On Fri, Feb 25, 2011 at 04:58:22PM +0100, Johan Herland wrote:
>>> Maybe we should use a slightly more verbose separator (i.e. more
>>> unlikely to trigger false positives). As you say, we already have to
>>> watch out for "---" because of "am", but that only applies to projects
>>> that _use_ "am" (i.e. mailing-list-centric projects like git.git and
>>> the Linux kernel). Other projects (e.g. github-centric projects or most
>>> centralized "$dayjob-style" projects) seldom or never use "am" at all,
>>> so I wouldn't expect those developers think of "---" as "special" in
>>> any way.
>>>
>>> What about using something like "--- Notes ---" instead?
>>
>> Yeah, it is true that many git users will never care about the
>> patch-through-mail workflow. And I think these days that is OK, because
>> rebase will take care to keep their commit message intact even if it
>> doesn't format well in a "format-patch | am" pipeline.
>>
>> I really wanted to keep it short and natural, though. Because eventually
>> I'd like to have this on all the time via a config option, and I don't
>> want to see "--- Notes ---" in every commit that doesn't have notes. But
>> I _do_ want to be able to quickly say "oh, let me make a note on this"
>> and just add a quick separator.

IMO typing "--- Notes ---" is quite fast. I suspect that most commits won't have any notes, so you'll have to type it rarely.

Also, what should be the template with notes enabled? Should there be the separator by default or not? Assuming notes are entered rarely, I think template should not have the separator. But if you use "--notes" command line option (i.e. interactive use), it should be there.

Show 5 quoted lines

> <bikesheding>
> What about "#---"? Satisfies the quick to type and is a lot less likely
> to appear in commit messages. Not sure about the implications of finding
> that string before the commit message is stripped.
> </bikesheding>

I think the separator should be:
1. unique enough so people won't enter it by accident
2. easy to remember, easy to type
3. descriptive so you won't have to look into documentation to see what "#---"
    means.

I think "--- Notes ---" fulfills all requirements.

Also, in case of separator with some text, like "--- Notes ---", we would like to be able to translate it probably, so I will see "--- Notatki ---" in Polish.

-- 
Piotrek