Luís Oliveira luismbo@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