ChangeLog file

[João Távora]

Luís Oliveira <luismbo at gmail.com> writes:

> made perfect sense back in the CVS days, not such much with a modern
> VCS. My second point is that energy wasted producing this kind of
> ChangeLog

See results of "M-1 M-x occur" on SLIME's Changelog for the string
"(slime-start)":

3 matches for "(slime-start)" in buffer: ChangeLog|slime

  10362:	* slime.el (slime-start): Added :directory argument and pass it to
       :	slime-maybe-start-lisp.
  10426:	* slime.el (slime-start): Continue even if the user, after
       :	prompting, didn't recompile the stale .elc file.
  12783:	* slime.el (slime-start): Don't set slime-net-coding-system ..
       :	(slime-read-port-and-connect): .. read it from the inferior lisp args.

In this example, some descriptions are better than others, but I
certainly don't think it's energy wasted.

Even with Git, reviewing a particular function's history requires either:

a) a wizard's knowledge of "git blame";
b) a tool that empowers you that level;
c) a ChangeLog file;
d) I'm pretty sure you can think of more creative methods :-)

'vc-annotate' is not quite b) yet and a c) is the next best thing I know
of. We probably don't want d) and maybe you know of some more b)'s...

> There's some redundancy between the ChangeLog and Git log that needs
> to be addressed.

Not "some"_!! Minus the useless line numbers, the example run in a
"*vc-change-log*" produces _exactly_ the same results.

But it adds the feature that a quick "C-m =" will bring you to that
particular diff, so you can see the actual *what*.

There are, of course, some (gratuitous) differences, like the ones
caused by these situations:

* You remembered to describe something more when writing the commit
  message. You should go and change the Changelog, but are too lazy.

* You remembered something after commiting and before pushing, instead
  of just "git commit --amend" from the shell, you should first change
  the ChangeLog first, but you are too lazy.

I think of this lazyness as the "good" kind, the kind that makes you
want to makes things better.

> That said, going through SLIME's ChangeLog I see plenty of useful
> explanations, so it might not be that much of an issue. I suppose
> going through each changed definition is a good review exercise.

We agree on this. That's why I think we should keep using the exact same
format. Just don't bother to store it twice in two different places.

In the meantime, if one uses vc-dir.el to commit it'll copy the
ChangeLog contents verbatim, and, I think, even discover what is new if
two commits by the same author were performed in the same day.

This BTW is a pain if you do it manually, and wouldn't be if only commit
messages were used.

The only problem is when you change the contribs, it would be nice to
have that particlar ChangeLog's entries copies as contrib/file.el to the
commit message.

> I agree with Helmut that waiting to see what Emacs does seems
> reasonable.

Yes, it's certainly reasonable.

> We both agree that a change log should describe the "why". My point is
> that the GNU ChangeLog format encourages describing the "what" (see
> for example
>
>> <http://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs>)

I agree that the section makes such misunderstandings possible,
especially if one reads only the example.

This is why I think you've misunderstood it: the accompanying text
speaks almost exclusively of format and it's advantages: the content
being characterized as "descriptions of specific changes". This leaves
the *quality* of these descriptions to the good principles of
programming, which can't really be described in a standard, don't you
agree?

João