What's the purpose of keeping a changelog if everyone uses their VCS properly?

Question

Every VCS that I've seen includes a means (and sometimes requires you) to make a log of what a particular commit does. If this history is being properly kept, what is the purpose of manually keeping the same history in a regular file?

Note that I'm not positing the changelog is useless, I just don't see a use for it myself. Are there other tools that use the changelog?

Answer 1

Basically, you're completely right. All the information should be in the VCS as well, and as commenters said, changelogs are often generated out of VCS information.

However, prepared changelogs come with some remarkable advantages:

• A changelog does not require to connect to the VCS, maybe install the proper VSC client before, scrolling through tons of commits, and such hassle. Instead, it quickly provides the required information in a neatly formatted document without much overhead.

• The audience reading the changelog may be developers, but often they're not. Or if they are developers, they lack the necessary inside knowledge to interpret raw VCS data correctly. So even if changelogs are to be generated from VCS data, the raw data may be still be cleaned up, consolidated or reformatted to make some points clearer to the audience. This becomes more important, the more the user audience differs (with regard to technical interna) from the product developers/contributors.

Answer 2

When used properly, VCS has too much detail. Every little change is recorded, when a changelog is generally for the big user-visible changes. In short, the target audience for a changelog is not the same as for the commit messages of the VCS.

If you are disciplined, a changelog can be an auto-generated subset of what is in VCS, though in my experience most teams don't do that.

By hand-editing the changelog, you (hopefully!) end up with something well crafted, easy to read, and with just the right of information for the target audience. Sort-of the "Clif Notes" of what has changed.

Answer 3

What's the purpose of keeping a changelog if everyone uses their VCS properly?
...
If this history is being properly kept, what is the purpose of manually keeping the same history in a regular file?

Your question is a good one, but you're making two big assumptions.

1. Given a team with a disciplined check-in history, you're assuming that the changelog should reflect or be equivalent to the check-in history. This is not the case. Over time, developers make many different types of commits to a project, some of which are technical in nature. These include configuration and installer-related changes. Some of these would be meaningless to someone who isn't intimately familiar with either the application or the code. While some project changelogs include all of the above, some are more focused on meatier items. [Ultimately, it's a judgment call.]

2. You're assuming that a software team could be disciplined enough so that the check-in history could serve as the changelog. There are two primary limiting factors with this utopian vision: 1.) Spelling mistakes, grammar mistakes, developer apathy, and developer fatigue yield an imperfect check-in history. Typically, development teams don't have either the time, inclination, or permission to go back after the fact and clean up the check-in history. 2.) Even when you consider excellent branching patterns (like GitHub Flow), people will make mistakes, and they'll have to check-in "that one little thing" that they missed after their "big boss" check-in. Again, this is why there are differences between your check-in history and your change log.