Question

Traditionally, developers (especially of open source projects) used to write a note about every single change with a description, the date and their name into a file called ChangeLog, CHANGES or HISTORY. This practice was created in a time where version control systems where not in wide use – nowadays people can simply type git log etc. to get that information, so why bother? Is anyone of you still creating a CHANGES file or something like that?

Then there’s the equally old NEWS file, which I only see in very few projects nowadays. This file is supposed to contain the big picture differences between releases – makes far more sense to me than the CHANGES file. Do you use such a NEWS file? What do you call it? Do you add entries for <1.0 versions? Do you add all the changes of the first version or do you simply write “initial release”?

I’ve looked at some newer projects like jQuery and Ruby on Rails for inspiration, and they don’t seem to have any of these files in their GitHub repositories.

Answer 1

I personally haven’t seen a voluntary, per-commit change log since the mid-’90s.

Not only do we now rely on version control for history, but unit tests allow us to refactor more frequently.

Version control provides not only the history, but also:

• Source diffs between versions. The diffs can help identify the cause of new defects.
• Reliable history. In a voluntary change log, changes might be omitted or deleted.