ChangeLog file

[João Távora]

Luís Oliveira <notifications at 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