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 <email@example.com> Fix compatibility issues with Emacs 28 * eat.el: Require 'subr-x'. * eat.el (eat-yank, eat-yank-pop): Pass three arguments to 'mapconcat'. * 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.
- Since I have to include a ChangeLog entry for each commit, I have to review my own changes before committing them. This often catches many bugs and typos.
- The ChangeLog entries are coupled with commits, so it gives a not too high-level description of each commit. It also describes the intentions behind a commit.
- If you ever break something, you can use the ChangeLog entry along
git blame(or equivalent command of your VCS), you don't need to pull out your hairs remembering the details of that change.
- It makes easier for others to understand your code and the changes made to it.
- If you leave the software for a while (e.g. half an year) and return it, you won't find yourself lost.
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.