Why keep a Changelog?
What is a Changelog?
A Changelog is a file that documents changes made to a codebase.
In its simplest form, it's a plain text file within a code repository, or it can be written in Markdown or reStructuredText or kept within a separate tool like Confluence or Sharepoint. Regardless of where it's kept, the main thing is the content.
It's not a copy of the Git log. It's a summary of the changes to be read by humans and for them to see what's changed, not a list of Git commits.
If you're considering using my open-source package, you can see what changes I've released, when, and what changes are due to release.
How is it structured?
Each version should have a heading specifying the version number and/or release date and a list of changes grouped by their type - whether something was added, changed, deprecated, removed, etc. This works well if you use conventional commits!
I like to follow a format called Keep a Changelog.
The headings link to a diff so you can see all of the commits and changes made to the code, and there's an Unreleased section that shows commits that have yet to be tagged and released.
If you need to present changes to a review or approval board, having an easy-to-read list of changes, separated by their type, is a much clearer format than a list of Git commits.
When should it be updated?
I recommend continually updating the Changelog rather than leaving it to just before a deployment. It's quick to add it to the Unreleased section as part of the commit and update the headings later.
Can I see an example?
Sure. See the one I added to the National Rail Enquiries feed parser library I've been working on or the Tailwind CSS starter kit theme for Drupal.
- Oliver
