Re: Is it time to drop ChangeLogs?

[Eli Zaretskii <eliz@gnu.org>]

> From: Mathieu Lirzin <mthl@gnu.org>
> Date: Mon, 07 Mar 2016 01:22:11 +0100
> Cc: 21998@debbugs.gnu.org, Lars Magne Ingebrigtsen <larsi@gnus.org>
> 
> In my short experience, Change Logs has generally been useful both when
> reading and composing them.  When writing them it helps me structure
> large changes in logical commits that are modelled by the Change Log
> format.  Finally It helps me being precise in my wordings which is not
> trivial for non-native english speakers.
> 
> On a more spiritual side, I think they belong to the zen of contributing
> to a GNU project.  :)

I agree completely.  Writing a log entry in ChangeLog format is an
excellent opportunity for reflecting on the changeset, for summarizing
its intent and final shape, and for making sure nothing was left out.
Writing those entries teaches one discipline, the ability to describe
your changes in just enough detail, and facilitates communications
between members of the development team.  And in loose teams such as
ours, good communications are everything.

As told many times in past discussions, ChangeLog files are also an
excellent first tool for forensics, easy to search with many available
tools.  It is invaluable when you don't have access to the repository,
and a good asset even if you do: traversing the history of a complex
Git repo without missing commits on branches is not a trivial task, it
requires using non-default switches and some rarely used commands and
options.  Even when you do use Git tools, ChangeLog frequently
provides additional important evidence.

So removing ChangeLog files will be a bad blow to our ability to
easily and conveniently research the past, something that is extremely
important in a project with such a rich history, where it's all too
easy to reintroduce a bug if you don't look hard enough at the history
of some code fragment.

People are saying it's an extra barrier to contributing.  That is
true, but so is understanding the Emacs internals, code conventions,
organization of the documentation system, its auxiliary files (like
CONTRIBUTE, NEWS, DEBUG, PROBLEMS, etc.), the release process, and a
few more things.  Having to write ChangeLog entries is an
insignificant addition to the body of knowledge a contributor needs to
master, there's no way around that.  Nor should there be: without
knowing this stuff, you cannot be a useful contributor anyway, as your
contributions will need too much attention from the veterans, who then
will be unable to make more significant contributions due to lack of
time.  We need here contributors who know enough to work on their own
with minimal guidance, who can be trusted to do a good job that
doesn't need to be reviewed too deeply, whose design can be trusted to
be in line with the Emacsy way of doing things.  How can one raise to
this position without learning a lot of project-specific stuff?  You
can't.

Writing ChangeLog entries is just one small part of that.  It's no
accident that people who don't want ChangeLog files more often than
not don't want to write detailed commit log messages, either, and many
times don't know how to write good documentation.  Do we want to
dispense with these as well?  If we drop the ChangeLog files, there's
no way we can explain why we ask for commit log messages in ChangeLog
format, so the next logical step is to drop that as well, and we will
then lose valuable information.  We already are firmly on that path.

Other prominent GNU projects that maintain ChangeLog files in the
repository include GCC, Binutils, GDB, glibc, and Texinfo.  XEmacs
also has it.  Why should Emacs be the first one to plunge into this
adventure?  Why not let others try that first, so that we could later
learn from their mistakes?  We have more important things to do than
waste our scarce resources on side issues, and too few people to do
them.

Let's reinstate the ChangeLog files.  Maintaining them is a negligible
cost; many other projects do that and don't have any trouble.  Unlike
what some people say, merge conflicts in ChangeLog files are very
rare, once you install git-merge-changelog.  We have some important
infrastructure based on ChangeLog files that will become extinct
without them, something that people tend to forget.  We tried to live
without these files for a year; that experiment failed miserably.
It's time to admit that, and fix the mistake we made.