Re: ChangeLog style (was: [PATCH 1/3] Add the ``--mount'' command line option)

[Sergiu Ivanov]

Hello,

On Fri, Jun 19, 2009 at 01:00:03PM +0200, Thomas Schwinge wrote:
> On Thu, Jun 18, 2009 at 11:10:19PM +0300, Sergiu Ivanov wrote:
> > On Wed, Jun 17, 2009 at 01:43:42AM +0200, Thomas Schwinge wrote:
> > > On Mon, Jun 15, 2009 at 10:39:22PM +0300, Sergiu Ivanov wrote:
> > > > * options.h (OPT_MOUNT): Add the definition.
> > > > (OPT_LONG_MOUNT): Likewise.
> > > > Update copyright information.
> > > > 
> > > > * options.c (argp_common_options): Add option ``--mount''
> > > 
> > > There is no need to put blank lines between changed files that are
> > > related to each other in the current changeset.
> > 
> > I'm sorry, but could you please give an example where there *is* a
> > need for a blank line? (I just feel a bit dizzy about that changeset
> > terminology :-( )
> 
> Sure, here we go -- and note that this is just my interpretation of the
> GCS, of how I think it should be done, and what I observe how it is done
> in other projects:
> 
> (a) A blank line is to be added it two independent changes are committed
> together -- which shouldn't be done in most cases in the first place, of
> course.
> 
>     * file1 (foo): Handle option bar here.
>     * file2 (bar): Use file1's foo instead instead of own implementation.
>     
>     * file1 (foo): Rewrite function.
> 
> Instead, first the ``rewrite foo'' change should be committed, and then
> the ``handle option bar'' one.  Remember that ChangeLogs are kept in
> reverse chronological ordering with respect to individual blocks
> (``rewrite foo'' (first change) is below ``handle option bar'' (second
> change)), but inside a block typically chronological ordering is used
> (``handle option bar'' before ``use foo'').

Aha, clear. I was aware of the fact that reverse chronological
ordering is used in ChangeLogs, but I didn't know about the ordering
inside blocks.
 
> (b) As a corollary to (a), a blank line is also needed when real
> ChangeLog *files* are being used, and a change is registered in there by
> the same author on the same day and no duplicate header line is being
> added.
> 
> Example:
> 
> ChangeLog file before the second commit:
> 
>     DATE  AUTHOR  EMAIL
>     
>       * file1 (foo): Rewrite function.
> 
> ChangeLog file after the second commit:
> 
>     DATE  AUTHOR  EMAIL
>     
>       * file1 (foo): Handle option bar here.
>       * file2 (bar): Use file1's foo instead instead of own implementation.
>     
>       * file1 (foo): Rewrite function.

I see. Now it's clear.
 
> To sum up: both these cases are not really relevant to us anymore, as (a)
> should be committed as two independent commits and (b) is no issue
> anymore as we don't have a real ChangeLog file anymore.

Great :-) So, I will forget about blank lines in commit messages in
99% of the cases.

> Further questions?

No, thank you :-) I feel quite confident in my knowledge now.

Regards,
scolobb