Implement a change log

  • 3 minutes

The concept of a changelog is simple enough: It's a file that has a list of changes made to a project, usually in date order. The typical breakdown is to separate a list of versions, and then within each version, show:

  • Added features
  • Modified/Improved features
  • Deleted features

Some teams will post changelogs as blog posts; others will create a CHANGELOG.md file in a GitHub repository.

Automated change log tooling

While changelogs can be created and manually maintained, you might want to consider using an automated changelog creation tool. At least as a starting point.

Using native GitHub commands

The git log command can be useful for automatically creating content. 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 standard tool is gitchangelog. This tool is based on Python.

GitHub changelog generator

Another standard tool is called github-changelog-generator.

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

This tool is based on Gem.

Should you use autogenerated log-based data?

Preference is always to avoid dumping log entries into a changelog. Logs are "noisy," so it's easy to generate a mess that isn't helpful.