Why should you maintain a ChangeLog using version control?

December 09, 2022

ChangeLog is a file contains the log of all the source files changes made. Some use ChangeLog to keep a list of user-visible changes, but that's not the correct use of ChangeLog, a NEWS file is the correct place for that.

GNU Coding Standards highly encourages to maintain a ChangeLog. So, I have started maintaining a ChangeLog for one of my Emacs packages, Eat (a terminal emulator). I'm not maintaining a ChangeLog file, I'm writing the ChangeLog entries as the commit messages, then I generate the ChangeLog with a Perl script taken from Emacs source.

For example, here a ChangeLog entry from commit 0cf617d60e of Eat:

2022-11-30  Akib Azmain Turja  <akib@disroot.org>

        Fix compatibility issues with Emacs 28

        * eat.el: Require 'subr-x'.
        * eat.el (eat-yank, eat-yank-pop): Pass three arguments to
        * eat.el (eat--eshell-term-name): New function.
        * eat.el (eat-eshell-mode): Use 'eat--eshell-term-name' instead
        of using 'eat-term-name' directly.
        * eat.el (eat-eshell-mode) [(< emacs-major-version 29)]: Use
        'eshell-last-async-proc' instead of 'eshell-last-async-procs'.
        * eat.el (eat--eshell-adjust-make-process-args)
        [(< emacs-major-version 29)]: Don't check and set ':filter' and
        ':sentinel' of 'make-process' argument plist.  Set process
        filter and sentinel from 'eshell-exec-hook'.
        * eat.el (eat--eshell-adjust-make-process-args): Call
        'eat--eshell-setup-proc-and-term' from 'eshell-exec-hook', not
        just after 'make-process'.

This is the GNU format, but you can use any format as you wish. If you take a look at it, you'll see that I have tried to describe each change I made. At first, I thought this was an overkill for my tiny project and going to be a wastage of time. But actually, this is extremely useful.

So I highly recommend to maintain a ChangeLog using your version control system (for example, Git, Mercurial, Bazaar, etc). Along with the benefits of a ChangeLog, you get much more, thanks to the well-written commit messages.