Frequently, the hardest part of writing release notes is gathering your list of changes. If you’re using project management software, this might mean checking Jira, Trello, or your Kanban board. If you’re working without project management software, this usually means going directly to your git commit history. There are pros and cons to each approach. There are also a few hacks you can use to improve on every method.
Below, we’ve laid out the benefits and drawbacks of each release note strategy, along with some tips on streamlining your workflow for the next time you need to quickly and easily compile a changelog.
How to Compile Release Notes Using Project Management Tools
Leveraging your project management tool’s mechanism for tracking releases is the most common way teams compile their release notes. But let’s be honest: Developers aren’t always known for tracking every piece of work in project management software (especially when tracking takes more time than the work itself).
When relying on project management software, missing small changes is common. It’s also common to erroneously think a feature made it into a release, when in fact it was merged too late to be included.
tl;dr: Compiling changelogs with project management software is usually imperfect. That said, there are ways to make the process easier.
Compiling a Changelog in Trello
One good way to quickly compile a changelog using Trello is to leverage the advanced search functionality. The following search, for instance, will find all cards in the “Done” list that were edited in the last week. This isn’t bulletproof, but it will work pretty well in practice.
An even more reliable way to do this is to get in the habit of archiving all the cards in your Done list after every release. That way, your current Done list will always reflect completed, unreleased work, saving you time on release notes in the long run.
Compiling a Changelog in Jira
Jira provides even more advanced search functionality than Trello. You should be able to concoct a query similar to the example above in order to find out what’s changed since your last release.
For a more reliable way of compiling your changes, you can also make use of Jira’s built-in release tracking tools.
Compiling a Changelog From a Kanban Board
No fancy querying available here. Simply take all your post-its out of the Done column, use them to build your release notes, and then get rid of them—or save them for future reference.
How to Compile Release Notes Using Git History
Using the git commit history for compiling changes in your software product is ideal because it is the source of truth for changes in your software.
That said, the potential problem with using git commits is that without some discipline, they are effectively useless.
Making Release Notes Easy With Conventional Commits
By leveraging keywords such as
chore, and others, you can use tooling such as conventional-changelog-cli or gitchangelog to automatically compile your changes into a CHANGELOG.md.
Furthermore, by leveraging associated tooling such as commitizen to write your commit messages and commitlint to ensure that no bad commit messages make it into your repository, you can minimize the amount of discipline required to make this work.
Once you reach this stage, you can generate changelogs effortlessly, and if you are releasing software intended for developers, you’re done!
If your release is intended for a broader audience, you’re nearly there too—the generated changelog can now be handed off to your team’s release manager as a basis for their human-readable notes.
Which Changelog Method Should I Choose?
For individuals or small dev teams, conventional commits are a huge productivity boost. Not only do they make writing release notes based on git history effortless, they also streamline everyday development.
For larger teams (or multiple teams), project management software is the more realistic way to wrangle that complexity.
I’ve Compiled My Release Notes—Now What?
If you’re building native apps for iOS or Android, check out Appnouncements, a service designed specifically for embedding beautiful, markdown-formatted release notes in your app in seconds.