Commit messages are often treated as an afterthought, when they’re one of the most powerfully enduring ways to communicate to future developers – including yourself. Release notes are respected even less, often generated from commit history and generally unreadable.
I’m going to show you why both are important, why they’re not at all the same, and why you should never generate one from the other.
11. Commit messages
What are they?
Brief, technical details
Mention the why
Audience: developers
Release notes
What are they?
12. Brief, technical details
Mention the why
Audience: developers
High-level summary of changes
Commit messages
What are they?
Release notes
What are they?
13. Brief, technical details
Mention the why
Audience: developers
High-level summary of changes
Mention the impact
Commit messages
What are they?
Release notes
What are they?
14. Brief, technical details
Mention the why
Audience: developers
High-level summary of changes
Mention the impact
Audience: your users
Commit messages
What are they?
Release notes
What are they?
16. Let’s compare
commit dea43e49
Author: Eva Parish
Date: Wed Nov 25 16:04:49 2019
JIRA-123: Upgrade to Emojilicious
library v2 for gif support
evaparish.com
17. Let’s compare
commit dea43e49
Author: Eva Parish
Date: Wed Nov 25 16:04:49 2019
JIRA-123: Upgrade to Emojilicious
library v2 for gif support
Release notes, v1.23
December 2019
● You can now create custom
emojis from GIFs. See the
documentation on Uploading
custom emojis for how to make
an emoji from your favorite GIF!
evaparish.com
18. So I have to write release notes, now what?
evaparish.com
19. So I have to write release notes, now what?
Be selective
evaparish.com
20. So I have to write release notes, now what?
Be selective
Change your perspective
evaparish.com
21. So I have to write release notes, now what?
Be selective
Change your perspective
Adjust the level of technical detail
evaparish.com
23. Let’s compare
$ git log --oneline
abc123ef4 Upgrade to Emojilicious library v2
for gif support
ad546c1ce Fix memory leak
d2bbc1c51 Change “OK” to “Accept” on modal
0c3fd8c47 Bump NPM version
ee6ab325e Change UI colors to improve
accessibility
dc13f828c Fix typo
98ea4f64c Refactor x to conform to style
f6ceec14b Bump UIBuilder
c7920929e Add CSS comment for metadata
0bae0b7e1 Ensure configuration is valid
98ea4f64c Fix broken tests
182169f36 Rename blog post
98ea4f64c Improve labels
21e54eb7b Support section widths in slideshow
evaparish.com
24. Let’s compare
$ git log --oneline
abc123ef4 Upgrade to Emojilicious library v2
for gif support
ad546c1ce Fix memory leak
d2bbc1c51 Change “OK” to “Accept” on modal
0c3fd8c47 Bump NPM version
ee6ab325e Change UI colors to improve
accessibility
dc13f828c Fix typo
98ea4f64c Refactor x to conform to style
f6ceec14b Bump UIBuilder
c7920929e Add CSS comment for metadata
0bae0b7e1 Ensure configuration is valid
98ea4f64c Fix broken tests
182169f36 Rename blog post
98ea4f64c Improve labels
21e54eb7b Support section widths in slideshow
evaparish.com
25. Let’s compare
Release notes, v1.23
December 2019
New features
● You can now create custom emojis from gifs.
See the documentation on Uploading custom
emojis for how to make an emoji from your
favorite gif!
Improvements
● We’ve updated the app with slightly different
colors to improve the experience of users with
certain forms of colorblindness.
$ git log --oneline
abc123ef4 Upgrade to Emojilicious library v2
for gif support
ad546c1ce Fix memory leak
d2bbc1c51 Change “OK” to “Accept” on modal
0c3fd8c47 Bump NPM version
ee6ab325e Change UI colors to improve
accessibility
dc13f828c Fix typo
98ea4f64c Refactor x to conform to style
f6ceec14b Bump UIBuilder
c7920929e Add CSS comment for metadata
0bae0b7e1 Ensure configuration is valid
98ea4f64c Fix broken tests
182169f36 Rename blog post
98ea4f64c Improve labels
21e54eb7b Support section widths in slideshow
evaparish.com
26. Let’s compare
$ git log --oneline
abc123ef4 Upgrade to Emojilicious library v2
for gif support
ad546c1ce Fix memory leak
d2bbc1c51 Change “OK” to “Accept” on modal
0c3fd8c47 Bump NPM version
ee6ab325e Change UI colors to improve
accessibility
dc13f828c Fix typo
98ea4f64c Refactor x to conform to style
f6ceec14b Bump UIBuilder
c7920929e Add CSS comment for metadata
0bae0b7e1 Ensure configuration is valid
98ea4f64c Fix broken tests
182169f36 Rename blog post
98ea4f64c Improve labels
21e54eb7b Support section widths in slideshow
evaparish.com
Release notes, v1.23
December 2019
New features
● You can now create custom emojis from gifs.
See the documentation on Uploading custom
emojis for how to make an emoji from your
favorite gif!
Improvements
● We’ve updated the app with slightly different
colors to improve the experience of users with
certain forms of colorblindness.
27. Let’s compare
$ git log --oneline
abc123ef4 Upgrade to Emojilicious library v2
for gif support
ad546c1ce Fix memory leak
d2bbc1c51 Change “OK” to “Accept” on modal
0c3fd8c47 Bump NPM version
ee6ab325e Change UI colors to improve
accessibility
dc13f828c Fix typo
98ea4f64c Refactor x to conform to style
f6ceec14b Bump UIBuilder
c7920929e Add CSS comment for metadata
0bae0b7e1 Ensure configuration is valid
98ea4f64c Fix broken tests
182169f36 Rename blog post
98ea4f64c Improve labels
21e54eb7b Support section widths in slideshow
evaparish.com
Release notes, v1.23
December 2019
New features
● You can now create custom emojis from gifs.
See the documentation on Uploading custom
emojis for how to make an emoji from your
favorite gif!
Improvements
● We’ve updated the app with slightly different
colors to improve the experience of users with
certain forms of colorblindness.
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? It's called Git. Right? Every time we commit code, we have to write a commit message, after all.
“Why don’t we just scrape a list of the commits that went into this release, and BOOM: instant release notes.” Right?
But, not so fast. I’m here to tell you why you should NOT do this.
Because, while having well written, consistent commit messages IS important...
And having great release notes is also important...
The two are not interchangeable! In the next few slides I’ll go into each one, and explain the different purposes and audiences of each.
So, starting with commit messages.
They 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 about the art of the commit that compared a commit message to a newspaper headline, and said:
“A good headline doesn’t have to tell 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 accomplished something--if someone wants to to read more about how you did it, they can 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.
You can assume that your reader is pretty technical, but they don’t have all the context. Again, this is why it’s important to include why you’re making a change.
Usually the person reading your commit message is another developer on your team, or someone on a downstream team who’s run into a bug and wants to know what you’ve changed that might have caused it. BUT IT CAN ALSO BE YOURSELF IN THE FUTURE.
This is where the title of my talk is sort of a lie: your commit messages can be *for you*, but it’ll be a version of you in the future that has forgotten what you did. This is a major benefit of docs that we don’t always talk about: you WILL forget things. You'll even forget about things you built.
To summarize: Commit messages are terse technical descriptions of what you changed in a unit of work and why, for an audience of developers.
Release notes, on the other hand, are a high-level, less technical summary of what has 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 less technical than your commit messages, and they should focus on resulting behavior, not how you did it.
And the most important thing to remember is release notes should be framed from the perspective of the end user.
So 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 to the user is.
What will the app be doing that is different, and how will that affect your users? What’s the impact?
Who is your audience for release notes? You may have already deduced this, but it’s your users.
There’s a wide range: depending on your product, your users might be super non-technical, or they might be developers 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 have 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.
So now that we know the difference, let’s look at how to write a commit message and a release note for the same change.
Let’s say we’ve upgraded to a newer version of the emoji library that we’re using so that we can make emojis out of gifs.
Here’s the commit message version. It has all the nice commit message things: there’s the ticket number, it starts with a verb in the imperative. It briefly mentions all the pertinent details--the library name, the version number--and efficiently states why: we want to add support for gifs.
Compare this to the release note version.
So, “You can now create custom emojis 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 little more room for information in a release note.
It starts by talking about what this change enables the user to do. It links out to further reading where they can get help if needed (side note, making sure that you’ve written docs for everything you’re highlighting in release notes is a great idea). And it ends with inspiration for what the user can do to start using this new thing.
You can also see that it totally omits the library name and version. That’s because user doesn't necessarily care about those thing. What they care about is what this change unlocks for them.
So. I've convinced you now that these are two different things. But 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!
From there: Pick out the changes that are most interesting or impactful to a user
Feel free to leave things out; there are plenty of things in your commit history that won’t affect a user.
The lack of curation is one of the main reasons I dislike when teams use commit messages as release notes: it gives everything equally important billing. Your user has to scan a list that ranges from huge breaking changes to fixed typos, 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 affect them? What differences will they notice in your product? Any breaking changes or action they have to take?
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 together.
And here are the two changes that I would make into release notes. One is the emoji example we went over earlier. The other is an app-wide change for accessibility.
And here are the corresponding release notes.
You can see 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 we wrote earlier.
And here’s the accessibility change -- notice that it focuses on how this affects users, specifically how it improves the experience for users with colorblindness.
Both commit messages and release notes 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 about what you’ve done in a way that’ll make things easier for your future self and your coworkers. It only takes a few extra seconds of brainpower to write a good, useful commit message, and if you get into the habit it barely takes that. And it’ll 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 you’ve put into building your product.
So: use both commit messages and release notes appropriately, and don’t waste these opportunities.
