Neil Killen

You’ve just come to the end of your sprint and it’s time to ship a new release to the QA environment for testing. But what about the release notes? In this post I’ll share some tips on creating useful release notes your team and customer will actually read and use. I explain why they are important and how they can help ensure a smoother release through to production.

Why do we create release notes?

Release notes are a way to convey to the business as well as the QA team what changes are included in the upcoming release. They are usually generated by Dev Team Lead as he/she is the gatekeeper for dev and responsible for what is allowed to leave development and go to higher environments.

What should you include?

Release notes should be short and concise I usually include the following sections:

• Overview – Release Number, created by, expected ship dates per env, actual ship dates.
• Pre-deployment steps – any steps that needs to happen prior to deployment. This could include a change to infrastructure or a module install etc.
• List of Features – you can run a script to get all completed feature PRs since last release.
• List of Bugs – you can run a script to get all completed bugs since last release.
• List of hotfixes – you had to hotfixed something in production those hotfixes also get merged into develop and should be included in the next release.
• Post-deployment Steps – this could include changes to content items or maybe a coveo index rebuild etc.
• Rollback process – list of steps for the team to quickly revert to the previous release. This could just be a link to another generic document.

Basically there should be nothing in the release that has not been covered in the release notes. We don’t want any surprises when we get to production.

Utilizing DevOps

Azure DevOps has a rich feature set for developers from source control, managing the backlog, automated build, release pipelines, testing everything you need for managing the application lifecycle. I’m also a huge fan of the wiki and a firm believer in documenting the solution and sharing that knowledge with team members and the business. You never know when a key member will get moved onto another project. Or in six months when the business requires changes for some complex feature you need to understand quickly how & why it was implemented in the way it was without having to dig into code. This documentation should be sufficient to bring you or a new developer to the team up-to-speed quickly.

The wiki is also the ideal place for capturing release notes you can easily link to bugs, stories or documentation on how to configure and test new features.

Refining Release notes

Release notes usually start off in a draft state and as we move up through the Environments they go through refining process: QA -> Stage/UAT -> until the point where the release is approved and ready to be promoted to Production. Once notes are created initially we ask the developers to review:

• All Stories/Bugs you have worked that has been PR’d and merged into develop since is included in the release notes.
• Pre-Deploy Steps – if there is anything you are aware of that needs to be completed please include.
• Post Deploy steps – if there is anything you are aware of that needs to be completed please include. Any content changes or Packages to be installed to support the release.
• Anything else that is relevant to ensure successful and smooth release to higher envs.

Bug and Story Lifecycle

As stories and bugs go through their various stages:

• New – a new item maybe it’s still in the backlog has not been assigned to a sprint and has not yet got suffice to information to start.
• Dev Ready – has sufficient information for developent to start, has been assigned to a sprint, is pointed.
• Active – developer is currently working on it.
• In Pr – developer has created a Pull request and is in the process of being reviewed or waiting to be reviewed.
• Ready for QA – pr has been completed successfully and it’s been merged into the develop branch and is on DevInt. Waiting to be included in a release to be shipped to QA.
• In QA – has been included in a release and has been deployed to QA environment and is being tested or waiting to be tested.
• Ready for UAT – qa is complete and it has been approved to be deployed to UAT.
• In UAT – is being tested in UAT by the business product owner or is waiting to be accepted by the business.
• Ready for Production – has been signed off by the business and is waiting to be deployed to production.
• In Production – done.

These are also reflected in the release notes so you can easily see at a glance the progress of a release. Simple queries in DevOps can retrieve this info.

Tracking Bugs and Features

What goes into a release depends on the priorities of the business, capacity of the team and your sprint and release cadence. Most likely you will decide during your sprint planning session the stories and bugs that will be included in the sprint and upcoming release. This may change during the sprint as higher priorities can occur most likely a bug identified in a release that needs must be addressed immediately before a release can be shipped to a higher environment. Although we try hard not to change a sprint once it’s started but it inevitably happens – that is agile!

DevOps provides a couple of extremely useful fields for tracking the release a bug occurred in when was resolved in or a feature was shipped in. By having the Developers and QA utilize and keep these fields updated allows for easy reporting and tracking of bugs and stories for every release with a few simple queries.

Feedback

Please leave a comment as I’m interested to hear if you do anything differently in for your release notes?