[RFC] Re: short and long log messages

[Matthieu Moy]

Alexander Belchenko wrote:
> John Arbash Meinel пишет:
>>
>> I think it would be a reasonable best practices. Just like how we
>> document functions:

I just noted that darcs does it roughly this way too.

When you commit ("record", in the darcs terminology), you're prompted
for a "patch name" from the command line, and then, you're allowed to
enter a "long comment", which opens a text editor with this:

| <what you just entered as the patch name>
| ***END OF DESCRIPTION***
|
| Place the long patch description above the ***END OF DESCRIPTION***
| marker.
| The first line of this file will be the patch name.
|
|
| This patch contains the following changes:
|
| A ./foo

Note the comment telling me about the first line (bzr could have this too).

>>
>> """summary line.
>>
>> more detailed stuff here
>> """

This is also Emacs' best practice.

> I never before use --line log formatter because it does not show
> revisions numbers. Few days ago I fix this behavior and now all can use
> --line for real work.
> 
> But I have a lot of history in my branches that does not follow this
> summary rule in comments. So, I think this change in --line behavior is
> too radically. I'd prefer to have another long option --summary instead.

Whether you call it --line or --summary will not make your old history
work with it. We already have --long, --short, and --line. I don't think
having 4 log formatters by default would be a good thing for bzr's
simplicity. If my proposal is adopted, then I think the current behavior
of --line should no longer be available in the core bzr. Perhaps move it
to bzrtools.

If you want to have a log formatter that don't use my proposal, you'll
probably not follow the convention. Then, when _I_ run bzr log on _your_
branches, I'll get crap output. In a distributed environment, you can't
do without a global convention, and nobody will use it if the tool does
not enforce it a little.

And I think we should take advantage of the pre-1.0 phase to set this
kind of things.

-- 
Matthieu