DEV Community

loading...
Cover image for How to Write a Proper Changelog

How to Write a Proper Changelog

estheragbaje profile image Esther Agbaje ・2 min read

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?
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.

Alt Text

  • Group changes based on release dates: All changes and updates made per release date should be grouped together.

Alt Text

  • 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.

Alt Text

  • 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.

Alt Text

Click here to view the changelog from Chakra UI

Discussion (1)

pic
Editor guide
Collapse
roalz profile image
Roal Zanazzi

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.