6

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?

Sean Allred
  • 837
  • 6
  • 14
  • 2
    People use changelogs, though you can often generate them from commit messages – ratchet freak Dec 13 '14 at 16:20
  • @ratchetfreak That was my thought, too. There is even a standard format for changelogs – you would think they can easily be generated from `git log` or similar. – Sean Allred Dec 13 '14 at 16:21
  • 7
    VCS history is for developers that want to know why this file was modified; change logs are for users that want to know what they'll get from an upgrade. – amon Dec 13 '14 at 16:33
  • @amon Excellent point, as Jens made also in his answer :) – Sean Allred Dec 13 '14 at 16:35
  • 1
    possible duplicate of [Should the commit history be used to convey critical information to developers?](http://programmers.stackexchange.com/questions/251587/should-the-commit-history-be-used-to-convey-critical-information-to-developers) – Jim G. Dec 21 '14 at 16:13
  • @JimG. Note that your proposed duplicate makes no mention of a `CHANGELOG` file and certainly no mention of end-users. What makes you think it's a duplicate, though? – Sean Allred Dec 21 '14 at 16:52

3 Answers3

7

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.

JensG
  • 2,423
  • 1
  • 19
  • 25
  • 1
    Emphasizing this point, my vcs commit log is full of entries like "refactor MemoryBlock to remove duplication in get methods" and "make SimplePageAllocator pass tests for exception throwing" but as both of these are internal classes that an end user of my project would never actually use, those entries wouldn't appear in a changelog, despite the fact that this project has developers as its target market. Only changes with end-user visible effects go into the changelog ("new implementation of page allocation should be better for small files, use CREATE_OPT_SIMPLEPAGEALLOCATOR to use it"). – Jules Dec 13 '14 at 18:08
  • BTW, changelogs can be generated from your issue tracker as well. [JIRA even offers a page for it](https://jira.atlassian.com/browse/GHS?selectedTab=com.atlassian.jira.jira-projects-plugin:changelog-panel). – JensG Dec 16 '14 at 10:42
6

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.

Bryan Oakley
  • 25,192
  • 5
  • 64
  • 89
  • 2
    This. Adding feature X may require 900 commits across multiple team members and bug fixes, but should be collapsed down to a single entry in the changelog presented to the user: "added feature X." –  Dec 14 '14 at 04:49
  • @Snowman: Please see my answer as well. – Jim G. Dec 14 '14 at 05:47
  • @JimG. yours is a good answer too, but the second paragraph of this one nicely sums up my main point about changelogs: aggregation (cliff notes, or summary) quite concisely. –  Dec 14 '14 at 05:49
  • @Snowman: Right. I upvoted this answer too. – Jim G. Dec 14 '14 at 15:27
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.

Jim G.
  • 8,006
  • 3
  • 35
  • 66