In many projects I have been a part of, we have found ourselves delivering code to clients via releases. These releases frequently need detailed release notes. Release notes are a valuable way for us to communicate to our clients but writing them can take a lot of time and effort.
To assemble our release notes, we would have to comb through all of the Pull Requests and commits made between versions to compile a list of changes. Then, we would need to write a few sentences explaining each change. There are usually multiple developers on a team, and sometimes explaining someone else’s code can be difficult. More often than not, I would need to track down individuals and ask them for the important details they felt should be included in the notes. Because of this, I frequently found myself dreading release day.
On our most recent engagement, we did our initial release this way and it took three hours to complete. Because this project released code weekly to our client for integration, this effort would’ve quickly added up. We decided that there had to be a better way, and we were right.
Releases Are A Team Effort
Here’s The Process We Arrived At:
Each week, when we planned a new sprint, we also created a GitHub issue to represent the sprint. For many projects here at Sparkbox we use ZenHub, which allows us to turn these sprint issues into epics. We then take advantage of ZenHub’s kanban board, which gives us pipelines to organize our work. The epic card then lives in the In Progress pipeline for the entire duration of the sprint.
Our Release Notes Template:
During a sprint for our most recent project, the developer writing the code also became responsible for adding their contribution to the release notes. To do this, we would start with a release notes template. The template would then be copied and pasted into the epic’s description. As work features and updates were completed, developers were able to add to the ever-growing list of release notes.
[Compare Diff](https://github.com/sparkbox/awesome-project/compare/vOLD_VERSION_NUMBER...vNEW_VERSION_NUMBER)
[Compiled Code](UPLOAD_A_ZIPPED_VERSION_OF_THE_LATEST_DIST_DIRECTORY)
# Release Notes
## New Features
* Description of the update (#PR_NUMBER)
## Updates
* Description of the update (#PR_NUMBER)
## Other
* Description of the update (#PR_NUMBER)
To ensure nothing was forgotten, cards were not allowed to be closed until the release notes had been updated. Our new definition of “done” was not just a merged pull request but a merged pull request that had been documented. At the end of the sprint, when it was time to draft a new release, we gave our compiled notes a quick review and then copied and pasted them into the release.
And that’s it. This simple change in our workflow made us considerably more efficient. Even more so, we also found ourselves writing more detailed release notes for our clients, and it gave everyone on the team a chance to be more involved in the release process.
