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

[Thomas Schwinge]

Hello!

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'').

(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.


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.


Further questions?


Regards,
 Thomas

signature.asc
Description: Digital signature