Re: changelog format

[Ludovic Courtès]

Hi!

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

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.  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,
rather than buried in the VCS history.

And change logs serve a different purpose: they give a higher-level view
of the diff, sort-of like a semantic patch.

Thanks,
Ludo’.