bug-standards
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: changelog format


From: Stefano Lattarini
Subject: Re: changelog format
Date: Wed, 23 May 2012 19:10:23 +0200

On 05/02/2012 11:52 PM, Ludovic Courtès wrote:
> Hi!
>
Hi Ludo.

> (Resending a message that Gmane had apparently swallowed.)
> 
> Stefano Lattarini <address@hidden> skribis:
> 
>> Then the ChangeLog is mostly useless, and writing it mostly a waste of time.
>> I'm not the fist one to reach this conclusion:
>>   <http://gcc.gnu.org/ml/gcc/2007-12/msg00016.html>
>>   <http://thread.gmane.org/gmane.comp.gcc.devel/94464/>
> 
> That’s the great misunderstanding about change logs.
>
I think there's no misunderstanding on my part.  I understand what the GNU
Coding standards recommend about the ChangeLogs; I just believe those
recommendations are outdated if not downright wrong, and should be fixed.

> What, to me, summarizes the rationale best is this paragraph (info
> "(standards) Change Log Concepts"):
> 
>      There's no need to describe the full purpose of the changes or how
>   they work together.
>
Which, followed to the letter, would make the ChangeLog entries basically
worthless for all but the most trivial commits.

>   However, sometimes it is useful to write one line
>   to describe the overall purpose of a change or a batch of changes.  If
>   you think that a change calls for explanation, you're probably right.
>   Please do explain it--but please put the full explanation in comments
>   in the code, where people will see it whenever they see the code.  For
>   example, "New function" is enough for the change log when you add a
>   function, because there should be a comment before the function
>   definition to explain what it does.
> 
> Indeed, it’s more convenient when the explanation is next to the code,
>
It depends.  The how and why the code works the way it works -- yes, that
must definitely must go in code comments (albeit in most cases, placing
also an "abridged" version placed in the commit message won't hurt).  But
the rationale of why a change is needed, and how it relates to previous
changes or attempts -- that must go in the commit messages (albeit in
some cases, reporting part of that history in code comments can be of
great help).

> rather than buried in the VCS history.
>
The two approaches are not mutually exclusive, but complementary: some
comments goes in the VCS history, some in the code/documentation, and
some in both places.

> And change logs serve a different purpose: they give a higher-level view
> of the diff, sort-of like a semantic patch.
>
This is a good aspect, but it complements rather than substitute the
higher-level explanation and motivation of a change.  Let me take a
recent Automake-NG commit as an example:

    [ng] config.h.{bot,top}: don't support anymore (distribution and deps)

    The use of those files have been obsoleted since Autoconf commit 5047ea80
    of 1994-08-09, "support alternate input file names"; yes, the "1994" in
    there is not a typo: those files were already deprecated in Autoconf 2.0.
    It's well past time to remove support for them!

    For more information, see chapter "Obsolete Constructs", section
    "acconfig.h" of the Autoconf manual.  See also the discussion on automake
    bug#7919, in particular the message <http://debbugs.gnu.org/7819#20>.

    * NG-NEWS: Update.
    * automake.in (handle_configure): Don't automatically distribute the
    'config.h.top' and 'config.h.bot' files if they exist, and don't add
    them to the '%FILES%' transform when processing the 'remake-hdr.am'
    Makefile fragment.  In fact, drop the '%FILES%' transform altogether,
    since now it would always expand to empty.
    (@common_sometimes): Don't list 'config.h.top' and 'config.h.bot'
    anymore.
    * lib/am/remake-hdr.am (%CONFIG_HIN%): Don't depend on '%FILES%'
    anymore.  That transform has been removed now (and wouldn't be needed
    anyway).
    * t/autodist-config-headers.sh: Remove as obsolete.

and examine it in detail.

SUMMARY LINE

    [ng] config.h.{bot,top}: don't support anymore (distribution and deps)

This says in a line what the commit does.  it is useful for people skimming
the VCS history (to quickly determine if the commit is relevant to them);
this is especially true for GUI/WEB tools like gitweb and gitk, which
present an overview of the history where only the summary lines are visible.

MOTIVATION AND REFERENCES

    The use of those files have been obsoleted since Autoconf commit 5047ea80
    of 1994-08-09, "support alternate input file names"; yes, the "1994" in
    there is not a typo: those files were already deprecated in Autoconf 2.0.
    It's well past time to remove support for them!

    For more information, see chapter "Obsolete Constructs", section
    "acconfig.h" of the Autoconf manual.  See also the discussion on automake
    bug#7919, in particular the message <http://debbugs.gnu.org/7819#20>.

This explains why the changes done by the commit are a good move, rather
than simple "code churn", giving detailed references.  If someone in the
future question the usefulness or goodness of the commit ("why have you
broken backward compatibility for such a small code simplification?") we
can answer him with rationale ("that was compatibility for an usage
deprecated by eighteen years").

DETAILED PER-FILE CHANGES

    * NG-NEWS: Update.

This is just noise, but is mandated by the GCS, and since consistency
is good, I'd rather have it than not.

    * automake.in (handle_configure): Don't automatically distribute the
    'config.h.top' and 'config.h.bot' files if they exist, and don't add
    them to the '%FILES%' transform when processing the 'remake-hdr.am'
    Makefile fragment.  In fact, drop the '%FILES%' transform altogether,
    since now it would always expand to empty.
    (@common_sometimes): Don't list 'config.h.top' and 'config.h.bot'
    anymore.
    * lib/am/remake-hdr.am (%CONFIG_HIN%): Don't depend on '%FILES%'
    anymore.  That transform has been removed now (and wouldn't be needed
    anyway).
    * t/autodist-config-headers.sh: Remove as obsolete.

This has the role of "semantic patch" you was referring to.  Don't just
report the single diffs (which already present in the "git diff" output
anyway), but explain why they are needed / makes sense.  True, there is
some duplication with what "git diff" would tell us anyway, that that's
acceptable (and as I've already stated in a previous message, having
some redundancy when explaining things to a human usually makes more
good than harm).

Regards,
  Stefano



reply via email to

[Prev in Thread] Current Thread [Next in Thread]