Why maintain traditional detailed ChangeLog in modern world (with SVN, Mercurial, Git)?

Question

Detailed ChangeLog entry usually tell who, when and what function changed and for why this change done.

And this for every separate function in the source code tree!

As I understand ChangeLog come from past when there were no good VCS.

So traditional ChangeLog doesn't need at all as you can get it all from:

  $ svn log .
  $ hg log .
  $ git log .
  $ bzr log .

Only one possible needs for ChangeLog for short summary between product versions and intended for user only (for example, when new version come, developer prepare ChangeLog describe notable/visible changes).

Or I am wrong?

From http://autotoolset.sourceforge.net/tutorial.html#SEC45 :

The ChangeLog file: Use this file to record all the changes that you make to your
source code. If your source code is distributed among many subdirectories,
and there is reason enough to think of the contents of the subdirectories
as different subpackages,then please maintain a separate `ChangeLog'
file for each subdirectory.

Look archaic and dogmatic. ChangeLog required by autotools and by "GNU coding standards".

GNU Emacs source contain a lot of huge ChangeLogs (many split by many parts):

  $ find emacs-22.3 -name "ChangeLog*" | xargs cat | wc -c
13605747

I can get summary log from Emacs bzr repo for about 1 min and search through it instead search for each separate ChangeLog and with modern tools like Emacs VC or Tortoise SVN/HG immediately get diff for change.

Answer 1

As you say, a manually maintained change log can be useful as a summary of user-visible changes, or as an overview of large-scale changes that might be hard to determine by looking at a lot of individual commit messages.

Answer 2

A changelog is useful for people who aren't developers and are looking to get a broader picture as to what has changed. While a changelog can get detailed, I wouldn't expect a user of any application I wrote to go through git log output to figure out what's changed.

Log output from your VCS is likely to be more fine-grained (i.e. you might have a commit that's labelled "fixed typos" -- is the user likely to care?) and not provide enough context. The changelog gives them that context.

Answer 3

In addition to your reasons (user only, etc), I think that they can be very useful while doing development. I often will make a couple changes before committing to source control and will annotate them in the change log while working.

Also, if changes are made and then removed, this may be harder to pick out of a source control revision log than a single file (e.g. just delete a line). As a side note, I tend to keep my change log under source control along side my source code.

Answer 4

Why write user documentation when we have comments?

Answer 5

With distributed VCS, it has become a standard to "Commit Early, Commit Often". With such approach, you will end up with more commits than you have actual new features or bug fixes. The changelog is supposed to summarize the changes to the application as a whole. The VCS log on the other hand shows history of the source code, i.e. how did the feature end up being implemented.