Keeping a changelong

I never use to keep a changelog for my projects, until I started to get more involved in making more complex projects for my own use. I will now not create a project without one, as it allows me to keep track of the project and its changes. So why should you create a changelog?

What is a changelog?

A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

Why keep a changelog?

To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.

How do I make a good changelog?

Guiding Principles

  • Changelogs are for humans, not machines.
  • There should be an entry for every single version.
  • The same types of changes should be grouped.
  • Versions and sections should be linkable.
  • The latest version comes first.
  • The release date of each version is displayed.
  • Mention whether you follow Semantic Versioning.
  • Types of changes
  • Use ISO Standard for dates.
  • Added for new features.
  • Changed for changes in existing functionality.
  • Deprecated for soon-to-be removed features.
  • Removed for now removed features.
  • Fixed for any bug fixes.
  • Security in case of vulnerabilities.

You can read more about keeping a changelog at keepachangelog.com which is run by Olivier Lacan