Keep 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.
Who needs a changelog?
People do. Whether consumers or developers, the end users of software are human beings who care about what’s in the software. When the software changes, people want to know why and how.
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
| Changelog Type | Description |
|---|---|
Changelog: added | Indicates a new feature or functionality was added. |
Changelog: changed | For changes in existing functionality. |
Changelog: deprecated | Indicates a feature or functionality is deprecated. |
Changelog: removed | Indicates a feature or functionality was removed. |
Changelog: fixed | Indicates a bug or issue was fixed. |
Changelog: security | In case of vulnerabilities. |