Implement a changelog

  • 3 minutes

A changelog is simple: it's a file that lists changes made to a project, usually organized by date. The typical format shows versions, and for each version lists:

  • Added features - New things you can do
  • Modified/Improved features - Things that work better
  • Deleted features - Things that were removed

Some teams post changelogs as blog posts. Others create a CHANGELOG.md file in their GitHub repository.

Automated changelog tools

While you can create and maintain changelogs manually, you might want to use an automated tool to help you. At least as a starting point.

Using native Git commands

The git log command can help you create content automatically. For example, create a new section per version:

git log [options] vX.X.X..vX.X.Y | helper-script > projectchangelogs/X.X.Y

Git changelog

One popular tool is gitchangelog. This tool is written in Python.

GitHub changelog generator

Another popular tool is called github-changelog-generator.

$ github_changelog_generator -u github-changelog-generator -p TimerTrend-3.0

This tool is based on Ruby Gem.

Should you use autogenerated log-based data?

It's usually better to avoid just copying log entries into a changelog. Logs contain too much technical detail, so it's easy to create a confusing mess that doesn't help users understand what changed.