How to Write a Proper Changelog

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.

Click here to view the changelog from Chakra UI