Commit messages vs. release notes: they’re important, they’re not the same, and they’re not for you


Eva Parish

Eva Parish

In this session from DevRelCon London 2019, Eva Parish explains the different purposes of commit messages and release notes, and how you can optimise each for better communication with developers and end users.


Eva: Hi everyone, thank you for coming. Thanks for being here for the last talk of the day. I wrote this talk because I’ve seen the following thing happen repeatedly. A team needs to start producing release notes to tell their users what’s changed, in some version of their product and they think, “Hey don’t we already keep a record of changes? We use Git, we have to write a commit message every time we commit some code, so why don’t we just scrape a list of all the commits that went into the last release, and boom, instant release notes?” I’m here to tell you why you should not do this. Because while having well written and consistent commit messages is important and having great release notes is also important, the two are not interchangeable. In the next few slides, I will tell you more about the differences between them and the different audiences for each.

But first, briefly about me. I’m a senior technical writer at Squarespace. In case you don’t listen to any podcasts and you haven’t heard of Squarespace, Squarespace provides a platform that let’s people build beautiful websites without needing to know how to code. It’s used by a lot of small business and creative people all over the world. I personally work with developers to write about how that platform works, on a small but mighty tech writing team. And we write internal documentation for the engineering department, so we still have users they’re just our coworkers and fellow developers. And we’re hiring so you can come work with me.

Starting with commit messages. Commit messages record brief technical details of what you’ve changed in a unit of work. The trick is to be brief but still complete enough that someone can get a sense of what happened. I read a great article that compared a commit message to a newspaper headline. It said “A good headline doesn’t have to tell you the whole story, but it should tell you enough to know what the story is about before you decide to read it”. A commit message should also mention the why. Why are you making this change? It’s less important to focus on the details of how you accomplish something, because if someone wants to know how you did it they can go and look at the diff. The reasoning behind the change is the harder thing to capture.

Next, let’s talk about the audience. Put simply, you can assume this is developers. Based on that you can assume that your reader is pretty technical but they don’t have all the context. And again, this is why it’s important to include the reasoning. Usually the person reading your commit message will be another developer that you work with, or maybe someone on a downstream team who has run into a bug and wants to know what you’ve done that might have changed this.

But it can also be yourself reading it in the future, and so this is where the title of my talk is sort of a lie because sometimes commit messages are for you. But it will be a version of you who has forgotten what you’ve done. This is a major benefit of docs that people don’t always talk about, which is that you will forget things, you’ll even forget about things that you’ve done. On my team we like to say that good documentation is like a love-letter to your future self. To summarize, commit messages are terse technical descriptions of what you’ve changed in a unit of work and why, for an audience of developers.

Release notes, on the other hand are a high-level and less technical summary of what’s changed about a product or a feature or an API in a release. When your product is an API for other developers to use, the lines get a little blurrier but as a rule of thumb, your release notes should be written at a less technical level than your commit messages. And they should focus on the resulting behavior and not how you did it. The most important thing to remember is that release notes should be framed from the perspective of the end-user. Rather than giving the technical details of that one library you swapped out, you might write you should notice faster performance in this area of the product, or whatever the benefit is to the user. What will the app be doing that’s different and how will that effect your users? What is the impact?

Who is your audience for release notes? You may have already deduced this but it’s your users and there’s a wide range, depending on what your product is. Your users might be super non-technical or they might be developers just like you. The important thing is to think about what information they need to know. Did you make some kind of improvement? Did you change how something existing works? Will they need to refactor code to remove an API you deprecated? What will look or feel different to them when they’re using the product? To summarize here too, release notes are a list of the important user facing changes in a release, generally written at a less technical level of detail and focusing more on behavior.

Now that we know the difference, let’s look at how we would write a commit message and a release note for the same change. Let’s say that we have upgraded to a newer version of the emoji library that we’re using so we can make emoji’s out of gifs. Here’s the commit message version. It has all the nice commit message things, there’s a ticket number, it starts with a verb in the imperative. It briefly mentions all the pertinent details, the library name and the version number and if efficiently states why, which is that we want to add support for gifs.

Compare this to the release note version. You can now create custom emoji’s from gifs. See the documentation for how to make an emoji from your favorite gif. You can already see that it’s longer, you have a bit more room for information in a release note. It starts by talking about what the change enables the user to do. It links out to further reading, where they can get help if needed, and as a side note, making sure that you’ve written documentation for everything that you’re highlighting in your release notes is a great idea. And it ends with inspiration for what the user can do to get started using this new thing. You can see that it totally omits the library name and version number because the user doesn’t necessarily care about that. What they care about is what this change unlocks for them.

I’ve convinced you now that these are two different things. How do you get started writing great release notes? While you shouldn’t recycle wholesale, you can look back through your Git history to remind yourself of what you’ve done, but from there pick out the changes that are most interesting or impactful to a user. And feel free to leave things out because there are plenty of things in your Git history that a user doesn’t care about. The lack of curation is one of the reasons I most dislike when teams use commit messages as their release notes. It gives everything equally important billing, so your user has to scan through a long list that ranges from huge breaking changes to fixed typos all mixed together and there’s no sense of ordering or ranking.

Now that you have your list of relevant changes, take each one and imagine it from your user’s perspective. How will this effect them? What differences will they notice in the product? Are there any breaking changes or actions that they have to take? And finally, remember to adjust the level of technical detail as appropriate, based on what you know about your users.

Giving you one last example to illustrate just how selective you can be. Here’s a whole list of commit messages that went into a made up release. You don’t have to read them all but they range from app wide changes to fixed typos, all mixed in together. And here are the two changes that I would make into release notes. One is the emoji example we went over earlier and the other is an app-wide change for accessibility. And here are the corresponding release notes. You can see upfront that it’s divided into new features versus improvements. This additional structure makes it even easier for users to orient themselves and know what you’ve changed. Here’s the emoji one which we went over and here is the accessibility change. Notice that it focuses on how this effects users, specifically how it improves the experiences for users with color-blindness.

Both commit messages and release note tend to be an afterthought in the development process but they’re actually easy, valuable ways that you can amplify your work. Commit messages are a chance to capture the context around what you’ve done in a way that will makes things easier for your future self and your coworkers. It only takes a few extra seconds of brainpower to write a commit message that’s useful. And if you get into the habit, it will barely take that and it will pay off. And release notes are an excellent opportunity to tell your users about the awesome thing you’ve built and why they should use it. If no one knows about a new feature or doesn’t know how to use it, they might just move on to some other product.

Good release notes get users excited about the hard work that you’ve put in to building your product. So use both commit messages and release notes appropriately and don’t waste these opportunities. Thank you!

Leave a comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.