Update your product, update your customers

How to Write a Changelog Like a Pro: A Step-by-Step Guide

How to write changelog like a pro

Scientist Pascal Cotte rocked the art world in the fall of 2020 with the news that his high tech camera had found a "hidden drawing" underneath da Vinci's masterpiece, the Mona Lisa.

It seems that Leonardo had, in the course of the 14 years he worked on the famous portrait, made several changes from his original idea. The sketch Cotte found would have produced a much different and less enigmatic painting.

Why da Vinci varied from his original design we'll never know.

What we do know is that Mona Lisa and her famous smile are a much-changed, and some in the art world say much-improved, version of her original charcoal self. Each change contributed to a better finished painting.

Which brings us to the task at hand: changelogs and how to write a changelog.

You may not think of yourself as a master on par with old Leo, but you have at least one thing in common with him. You know the effect a necessary deviation from the original plan can have on the outcome of the final product.

After all, that's what changelogs are for, right? Recording and storing all the changes, fixes, deprecations, and additions made to your software.

Like old Leo, you know that sometimes, the original just isn't quite as good as it could be.

Our goal today is to teach you how to write a changelog that is worthy of your time, your team, and your software. We'll be covering:

  • Why putting the latest changes first is best
  • Grouping and dating changes is good for UX
  • Short and sweet is the name of the game
  • Formatting is everything for the reader
  • How to categorize and label for easy use
  • What not to do with your changelogs

By the time we're done, you'll know how to write a changelog that will be useful to your team and worthy of the time and effort you put into them.

We may not help you create a masterpiece, but we'll certainly help you make your changelogs a thing to be proud of. Let's start learning now.

Step 1 - Use Reverse Chronological Order

Your team puts a lot of work into their software updates. For some, changes may be an ongoing, almost daily thing (looking at you, GitHub) while for others, quarterly changes are all that's needed.

When tracking these changes, regardless of how often they are made, the most recent are typically the most relevant.

Which is why the best way to write a changelog is to list changes in reverse chronological order, with the latest and newest changes appearing first on the list.

Your changelog users need to be informed of the most recent updates so that when they have an issue with your software, they know what to do to resolve it. They don't have the time or patience to wade through months, or even years, of updates to find what they need.

Step 2 - Group and Date Updates Together

There are two possible rules of thumb when it comes to grouping and dating your changes in your changelog. We're going to discuss both, so that you know how to write a changelog that suits your needs best.

  1. Group all changes from any given day together. This is the most common way of writing changelogs. However, some teams find it burdensome, especially when the updates affect different areas of the software or end-users—or both.
  2. The other option is to group together all changes made by one team or to one section of the software on any given date, giving each department or affected user their own section in the changelog.

The image below shows GitHub doing just that, with two updates released on the same day; one affecting their Cloud users and the other their Security customers.

GitHub changelog screenshot

As we said, there's really no right or wrong choice here. The decision depends on how often you update your product and how many updates are made and published when you do. You could try both grouping options to see which one works best for you and your team.

Step 3 - Keep Your Changelog Entries Short, Simple, and to the Point

Changelogs have one main purpose and that's to inform the user of changes made to the product so they can resolve any issues those changes may have caused. Informing stakeholders and other team members is secondary to this main mission.

And because that is their main goal, keeping changelogs short and to the point is vital. You're not writing War and Peace here. Give the user what they need to know and go on your way.

HubSpot changelog entry

Another key to writing a changelog that is most helpful to the user is to use simple, easily understood language. Everyday common speech is usually best. There's no need to make them seek out a dictionary.

Some technical terminology may be necessary, but that's acceptable since your changelog is for your developers and for users familiar with that vocabulary. That said, try to avoid jargon as much as possible, as well as acronyms and abbreviations.

Either one can create a confusing mess out of an otherwise perfectly clear changelog. Don't overcomplicate things. Remember the KISS of genius: Keep It Simple, Sweetie.

Look at the screenshot of a HubSpot changelog entry above. Notice the plain, simple, easy-to-understand language. Notice, too, the use of terms like “we've” instead of “we have.” It all goes toward keeping the entry short, simple, and to the point while still being friendly.

Step 4 - Format Your Changelog Entries Properly

Ever read a blog post or news item that was just paragraph after paragraph—and fat long ones at that?

Wasn't very easy to read, was it?

No one wants to read a changelog like that, either.

That's why formatting your changelog entries in easy-to-read, scannable ways is another key step to writing them.

Take a look at this entry from MailChimp's changelog:

MailChimp changelog entry

It's tagged with its relevant topic and audience, just as you would tag a blog post. Next, it uses the subheaders "What" and "Why" to break up the text.

And then, they go so far as to color code both the computer coding entries and the link to the Batch Subscribe page on their website using different colors. Again, just as a blog post would do.

All of the time and care put into that formatting makes their changelog easy-to-read, just like a good blog post.

Step 5 - Categorize and Label Changelog Entries

MailChimp does it with the one word tags at the top of their entries. GitHub does it with little red "bubbles" that sit underneath the headline. Look below and see how ReadMe uses icons for the same purpose.

ReadMe changelog examples

That purpose is to categorize each different type of update made to the software. A bug fix, an improvement, an addition, a new feature, and deprecations should all have their own category and the user should have an easy way of finding them.

Why? Because not every user has the same issue at the same time. And because not every type of possible update gets completed each time updates are published.

By using some sort of label or icon to indicate what type of update is included in the changelog entry, you help to keep your changelog user-friendly and well organized.

What to Leave Out of Your Changelog

No article on how to write a changelog would be complete if we didn't tell you what not to do. Here's the Rotten Dirty Three of writing changelogs:

  • Commit log diffs: No one, really, is interested in reading commit log diffs. Not even the guys who make them. The point is not to use these weird bits of developer geek speak either in, or as an excuse for, a changelog.
  • Confusing dating: No, not the Tinder kind of dating. Rather, the confusion that can be caused by formatting the dates in your changelog differently. Best practice is to use the ISO standard of YEAR-MONTH-DAY, especially if you have an international team or customers.
  • Forgetting to include deprecations: If what you're doing is going to break something for the user, for the sake of all, tell them! Don't make them guess as to why the software did something yesterday and won't today.
ReleaseNotes software better choice for tracking

Release Notes vs. Changelogs

You're probably wondering why a bunch of guys who have committed a lot of time and effort into developing software that creates release notes care if you know how to write a changelog.

The answers are pretty simple, actually. First of all, we recognize that some software companies use both an internal changelog and an external-facing release note system. After all, they do sort of serve two different audiences.

The second is that we hope we can convince you that our ReleaseNotes software is a better choice for tracking and publishing your updates than a changelog is.

The table below briefly spells out some of the main differences between changelogs and release notes, in case you need help deciding which one (or both) is right for you. We've got a whole blog article dedicated to the subject, if you need more info, too.

Task Or Purpose

Changelog

Release Note

Informing internal and external teams of developers 

Informing external users, stakeholders, and internal non-tech departments, like marketing


Branding and marketing opportunities


Tracking changes made to software

Social media and email content



As you can see, release notes are more versatile and give you more than just a log to track your updates. That's why we think they're the best solution for every software company. If you'd like more info, check out our website, complete with a demo.

We can't guarantee that your software will end up as famous as Mona Lisa or that you'll become the developer world's next da Vinci. What we can promise is that your changelog will get better, and maybe (just maybe), you'll be willing to give release notes a try.

And that's something to smile about, eh Ms. Lisa?

Frequently Asked Questions

When do I need both release notes and a changelog?

When you:

  • Make a lot of updates that affect users as well as your internal team
  • Have a lot of users who need to know about your updates, such as the developers who build on top of Shopify's eComm platform
  • Make changes that may affect stakeholders as well as developers
  • Want your updates to be accessible to both developers and the average user

Why should I choose ReleaseNotes software?

We could go on all day about this one, but here are the high points:

  • Our software is well-made, but reasonably priced.
  • It gives you the opportunity to turn release notes into email and social media content, thereby reaching a wider audience of users.
  • It takes the guesswork out of publishing your release notes.
  • Our software allows for labeling and other customization options.
  • Our customers like us. Here's a testimonial from one of them:

“Releasenotes.io massively streamlines our communication channels and has helped reduce the hassle of keeping all of our customers up-to-date.” - Wolfgang Reinhardt, Chief Product Owner, wescale

Who is ReleaseNotes software for?

Really, anyone involved in your software's development and updates. We're used by project managers, lead developers, development team members, and more. If you or your department make changes to your software, you can benefit from using ReleaseNotes.

Subscribe to ReleaseNotes.io

Sign up now to get access to the library of members-only issues.
Jamie Larson
Subscribe