Luís Oliveira notifications@github.com writes:
FWIW, I find the ChangeLog distracts people from more IMHO more important efforts such as updating the NEWS file or writing a proper commit message describing why something has changed rather than what.
I don't agree at all: you *should* describe in the ChangeLog or commit messages **why you changed what**. In the NEWS file, you describe the user-visible aspects of your change.
The ChangeLog format can hardly be blamed for any lazyness to write proper commit messages, indeed it encourages the opposite. The information in SLIME's ChangeLog has been invaluable to my recent hackings, for example.
I refer you to the discussion in emacs-devel, they're getting rid of the ChangeLog file, but not its format.
Still, Helmut, I propose that we get rid of the ChangeLog files and use commit messages exclusively.
I've noticed that with no such file, pressing C-x 4 a will still create a (dummy) ChangeLog file with the prettily formatted entries. You just don't commit it and it can probably be ignored in .gitignore.
Then, a fairly recent Emacs's built-in vc-dir.el will, upon commiting, automatically transpose the text below the date-and-author line is to the commit message buffer. This is extremely convenient and I invite you to try it (in other versions, you have to copy&paste and remove the left indentation manually).
Finally, emacs's own "M-x vc-print-log" will give you all the information. The actual diff is only the "=" keybinding away.
If Helmut agrees, I see the following steps to enable this in SLIME:
* We must find a way to re-implement version checking between SLIME and Swank that is portable across all installation options. slime.el can parse itself on compile/load to look for the ";; Version:" cookie (that MELPA and other automated builders also look for, incidently). swank.lisp would have to do something similar in portable Common Lisp to report its own version in a variable.
* Listing the contributors in the manual depends on the ChangeLog, but that can be delegated to some variation of
git log | grep Author: | cut -d ' ' -f 1 --complement | sort | uniq
except for the authors of patches that were commited by someone else in the CVS days.
* The CONTRIBUTING.md file has to be updated.
Anyone up to perform these changes?
João
On Sat, Jan 11, 2014 at 2:18 PM, João Távora joaotavora@gmail.com wrote:
I don't agree at all: you *should* describe in the ChangeLog or commit messages **why you changed what**. In the NEWS file, you describe the user-visible aspects of your change.
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) which 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 would be better pointed towards updating the NEWS file as well as proper commit messages.
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.
There's some redundancy between the ChangeLog and Git log that needs to be addressed. I agree with Helmut that waiting to see what Emacs does seems reasonable.
Just my 2 cents,
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
On Sat, Jan 11 2014, João Távora wrote:
[...]
I refer you to the discussion in emacs-devel, they're getting rid of the ChangeLog file, but not its format.
Still, Helmut, I propose that we get rid of the ChangeLog files and use commit messages exclusively.
AFAIK, the Emacs maintainers haven't dropped ChangeLog files yet or even made a decision. They discussed it in the context of the switch to git, which is also not yet completed.
I'd rather take a wait-and-see approach here. Let's see what the Emacs maintainers do, let them upgrade the infrastructure and fix most of the bugs; if it looks good then we do something similar.
It seems to me, that people who are too lazy to write decent ChangeLog entries are also unwilling to write decent commit messages. So I think that problem will not be solved.
Helmut
Helmut Eller eller.helmut@gmail.com writes:
On Sat, Jan 11 2014, João Távora wrote: [...] AFAIK, the Emacs maintainers haven't dropped ChangeLog files yet or even made a decision. They discussed it in the context of the switch to git, which is also not yet completed.
Well, regarding ChangeLogs I took a stance similar Stefan Monnier's which is the dev leader.
entries are also unwilling to write decent commit messages. So I think that problem will not be solved.
Agreed, I didn't say it would. I've just noticed that I have had to ask a couple of contributors already to additionally provide changes to a ChangeLog file, which could be cut down to one step only, and reduce friction. To pull in useful fixes from Attila I "had" (I decided, actually) to do the ChangeLog thing myself.
(BTW I've recently added a ChangeLog to yasnippet myself, to explore "C-x 4 a" but am now getting rid of it and using the same function only without ChangeLog).
Currently SLIME doesn't seem to have as many active and experienced contributors as Emacs. The github "masses" are used to commit messages, which can be checked and iterated much easier than Changes to a registered file in the repository.
João
-
Helmut Eller -
joaotavora＠gmail.com -
Luís Oliveira