A few days ago, I updated the changelog for Chakra UI and learnt a couple of things about documenting a changelog.
I decided to share them below:
Not sure of what a changelog is?
A changelog
is a curated record of all notable changes for each version of a project. These changes could be bug fixes, updates, new features, etc.
Why is it important to have a changelog?
- It makes it easy for contributors and users to see at a glance the updates made between each release of the project.
- In a situation where there’s a break in the project, the changelog helps you to easily track down the point where this break occurred.
- Changelog also serves as a means to keep users excited about bug fixes and new features of your project.
How to write a good changelog
- Put the latest changes first: While it is good to keep a record of all changes, it is important to place the newest changes and updates first. That is, use a reverse chronology when documenting the changelog. Why? Most people are truly interested in the latest changes so show it first.
- Group changes based on release dates: All changes and updates made per release date should be grouped together.
- Keep it simple and short: Since the goal of the changelog is to make changes easy for users to track, it makes sense to write in plain English and avoid unnecessary technical jargon.
--
- Format properly: The changelog should be easy to read and skim through. Utilize the use of headings and bullet points when writing your changelog.
- Categorise the kind of changes made and add it as a prefix before the summary of the change. For example, was it a bug fix or a new feature that was added? The use of
legends
can be very useful here.
Top comments (1)
I would recommend reading keepachangelog.com/en/1.0.0/
and using ISO8601 date format (YYYY-MM-DD) that has a LOT of advantages over the various national formats.