Re: Commit netiquette.

[Miles Bader <miles@gnu.org>]

Eli Zaretskii <eliz@gnu.org> writes:

>> Of course, people could also provide summary lines in a ChangeLog --
>> e.g., prefix a classic ChangeLog entry with a "SUMMARY:"  line.  Indeed,
>> I'd recommend that people do this, even though it's not a part of the
>> classic ChangeLog format (I do this sometimes when adding a single
>> cohesive change that touches many files); it makes ChangeLogs easier to
>> read and more useful.
>
> However, the "SUMMARY:" part just wastes precious real estate of the
> single line produced by "bzr log --line".

Eh?  I'm confused... I don't mean they should literally write the string
"SUMMARY:", and I was talking about ChangeLog files, not commit-logs.

What I was advocating was, _in ChangeLog files_, a style like:

   2010-02-22  Miles Bader  <Miles Bader <miles@gnu.org>>

           Frobbed the grot system:
           * grot-blah.el (fun1, fun2): Blurged frebly.
           * grot-zung.el (fun3): Nug n ug.
           * some-grup.el (zoon): Wabawaba.

This isn't always necessary for small/trivial changes, but for longer
ones, i think it's a useful addition.

Indeed, one can imagine a ChangeLog style where the commit-log text
(following typical commit-log conventions) is used a prefix for
traditional ChangeLog-type per-file entries.  For instance:

   2010-02-22  Miles Bader  <Miles Bader <miles@gnu.org>>

           Frobbed the grot system
           
          The Grot system was blorked, so rewrite all the zoong-nurbs
          using an explicit snood cache.

           * grot-blah.el (fun1, fun2): Blurged frebly.
           * grot-zung.el (fun3): Nug n ug.
           * some-grup.el (zoon): Wabawaba.

Again, all the comments above pertain to ChangeLog files, not
commit-logs [for commit-logs, of course I recommend the standard 1-line
(without period) summary followed if necessary by a more verbose
description in additional paragraphs].

-Miles

-- 
"... The revolution will be no re-run brothers; The revolution will be live."