Release management with Jira & Confluence
The ability to release software quickly and efficiently is pivotal to staying ahead of the competition. However, release management is a complex & dynamic process, if you want to get it right. There are many moving parts & making them work in unison could be a challenge. As the size & frequency of the releases go up, so do their intricacy. That is where the combination of Jira & Confluence comes into the picture. With these tools, and with right direction & processes, any team can nail down the exact flow that works for their unique release management philosophy.
In this article, we look at practical ways to use Jira & Confluence together to streamline your release management practices. Mind you though, we are not prescribing a certain approach over the others. We will simply point you towards a solution along with relevant examples, but customizing this approach for your ways of working is a responsibility you have to take.
Before we jump into the practical guide, let us first quickly brush up the release management concepts that will be handy when we look at the practical instructions in the latter half.
Release management basics
What are releases in software development
A release or a version in software development refers to the collection of changes that will roll out to customers (internal or external) at once. In layman’s terms, releases are buckets containing bug fixes, new features & enhancements etc.
For teams that focus on iterative delivery, the release (event) is just one part of the entire
release management cycle.
Broadly, each release can be categorized into major, minor or a maintenance release depending on the nature of changes included in that release.
You may have guessed by now the scope of each type of release.
Primarily focused on minor enhancements or bugs
These typically involve significant changes
Concentrated on fixing bugs or updating underlying infrastructure
These categories are not fixed and could be vastly different across various organizations
depending on their internal glossary. In fact, some development teams might even have few different types that we haven’t covered above.
Benefits of delivering software in releases/versions
Obvious question follows – why bother delivering software in release packages? Well, there are many advantages in doing that. However, 3 key benefits stand out.
The biggest benefit of delivering software in releases/versions is ease of maintenance. Tracking changes in a release becomes just a matter of being organised. And that guarantees the long term stability & reliability of the software over time.
Another aspect that benefits due to use of releases in software delivery is communication with stakeholders. Whether the stakeholders are internal or external does not matter. With releases, there is clear demarcation between different delivery milestones. Planning and execution of delivery is easy to visualize with such an incremental approach.
Iterative releases ensure that the product team has the potential to test their hypotheses, gather customer feedback & improve the product, with a quick turnaround time. Result is a better user experience. This aligns well with the agile principles & ofers a quick correction path in case of failed experiments.
How to name your releases/versions
We have now looked at different types of releases along with the benefits of delivering software in releases.
Before starting with planning your releases, we need to know how to name them. Many teams realize the importance of consciously naming their product releases only when it becomes too difficult to make a change. The logic behind naming your releases should be – these names should convey meaning to relevant stakeholders. Now who these stakeholders should be, what meaning should be conveyed that is completely up to you. But a thought through & structured release name definitely says a lot about your software development process.
In practice there are 4-5 different approaches to name your product releases. These are listed below along with their brief explanations –
Elevate Your Potential: 50 Inspiring Release Notes Examples To Inspire You
Different approaches to name your product releases
This is probably the simplest one. Date of release becomes the name of your product release. For example, a version that was released to customers on 15th April 2023 can be named as 2023.04.15 or whatever date format that is convenient to your audience.
Another variant on this one is, if there are monthly releases you can simply use the year & month to indicate the release number. For example, a release in April 2023 can be named as 2023.4 or something similar.
Suited for simple SaaS products.
Slightly different from the numeric naming of versions, here alphabets are prefixed or suffixed to add more information upfront. For example, a desktop software that works on windows & linux operating systems might name versions such as 2.3-windows & 2.3-linux. Or if you have slightly customised variants of your product your release names could look like 2.3-standard & 2.3-advanced.
This approach is nothing but extended numeric versioning. The only difference is – in here, there are predefined rules & guidelines to be followed before coming up with the next release name. For example, 2.2.1 might mean 2 – major upgrade, 2 – minor upgrade, 1 – patch upgrade. Here, the version could jump from 2.2.1 to directly 2.3 or something else depending on the predefined rules.
This is the most common approach because that’s how desktop software products are usually named & SaaS is a comparatively new phenomena. The version names here consist of various numbers such as 1.0 or 2.2.1. Every number has different significance and indicates to the stakeholders whether they should immediately upgrade to the new version or not. For example, the first number can refer to the major release identifier followed by a minor release identifier.
Relic of pre-SaaS era when software was sold via licenses.
If you have used an Android device, you know what we are talking about. Kitkat, Lollipop these are some of the names for Android operating system versions. Codenames usually make a good choice when you are dealing with a B2C product. Names of cities, animals, celestial objects are commonly used in such scenarios.
Suited for B2C produdcts
Keep in mind though, these are just common practices. You can create your own naming approach by mixing any of the above or even by coming up with something that is completely out of the box.
Different ways to plan releases
Enough about the definitions & nomenclature methods. Let us jump into the core of release management – release planning. Release planning can follow different frameworks & methodologies depending on the product, expertise & inclination of the team involved and a few other factors. At a very high level, this planning can take below mentioned approaches:
Agile release planningBreak down the software development process into small iterations called sprints & you are taking the agile approach to release planning. Each sprint lasts for a specific period, typically 2-4 weeks and includes a set of features that are prioritized based on their business value. Measured customer value & retrospective feedback from the stakeholders, contribute to the next cycle of release planning activity. One release can consist of the delivery coming out of multiple sprints or there could be a release at the end of every sprint, this is up to the team.
- Feature based release planning
If you are focused on building your software product from the customer journey map standpoint, it may make sense to group features into logical sets & release them together. For example, an e-commerce software product can plan an end to end delivery tracking capability in a single release.
In this approach, the features are prioritized based on their business value and get released when they are ready. Since there is no fixed sprint duration, this approach allows for a little more flexibility. - Time based release planning
Agree on a release date & continue to work on prioritised list of backlog items. Eventually, what gets included in the release is dependent on what items are ready to be delivered. The development team then works towards meeting the deadline by prioritizing the functionality that is most meaningful to that release.
- Continuous release planning
This is probably the most complex release planning approach & requires a good amount of groundwork & team maturity before it can be implemented in any team. It involves continuously releasing small updates or enhancements as they are developed. Continuous integration & deployment play a crucial role in making this endeavour work.
Here again, there is not going to be a perfect fit for what you want to do. You will have to experiment, improve & then revise the planning philosophy depending on the results being delivered.
Don’t hesitate to play around with diferent approaches & then get valuable feedback from the entire team to make course corrections.
Release management KPIs to keep an eye on
Tracking key performance indicators (KPIs) can help teams assess the effectiveness of their processes & identify areas of improvement. While there are numerous KPIs for keeping your release management process on track, here we look at the 4 basic ones. These are sufficient in the initial phase when you are trying to figure out what works for your team & what doesn’t.
KPIs for Release Management
Frequency
Simplest of all. How often a new release is going live to your end users, that’s your release frequency. Whether you want it measured per month, per quarter or per year – that’s up to you. However, the caveat is, you will want to consider the type of releases for coming up with the frequency number. For example, higher frequency but with most of them as patch releases may not be a good thing. It would rather indicate a problem in the quality of your team’s delivery.
Cycle time
This is the time taken from starting the software development to delivering that change to your customers. Longer cycle time may indicate inefficient release management processes. This one is going to be a bit difficult to measure and most likely, you will have to rely on some tools to give you this number. In case of Jira, this is available in ‘Cycle time report’. We will talk about this report in some detail in the latter part of this post.
Success rate
While frequency & cycle time are proxies to gauge efficiency of your process, your go to KPI for understanding quality of the delivery is the release success rate. It refers to the number of releases that your team delivered which were free of any major defects and met the requirements at a broad level. While the definition may make this KPI sound a little subjective, it isn’t. Every team should have its own definition of done for the release being called a success.
Rollback rate
This is another measurement for judging the quality of release delivery. It simply counts the number of releases that had to be reverted. Underlying reason for reverting could be anything ranging from quality issues to infrastructure stability. Higher the release rollback rate, more scope for improvement in your release management processes. Proper documentation accompanying your release process will enable you to measure this KPI easily.
You can combine the above basic KPIs with some advanced ones & get the desired ‘bird eye view’ across all your release delivery parameters. What matters is that you pro-actively try to improve your processes, however good they already are.
Making the most of your releases with release notes
Planning, execution & KPI measurement is not the sum total of release management. The end goal of any software release delivery is – adding value for the end users of that software product. But this value addition is after all a result of experimentation. You might end up doing a great job in one of the releases but not so impressive in another one. The prerequisite to understand your customers’ point of view is to first tell them what changes you have brought in to the product or service. Only then the real feedback will start trickling in.
And this ‘telling the customers’ part is taken care of by release notes. However, don’t mistake the ‘customers’ for only external users who actually end up paying your organisation for the product/service you deliver to them. ‘Customers’ can range from internal business stakeholders, frontline support team members to marketing & sales staff, in addition to those ‘real customers’. All these personas want to know different things about the release you just delivered.
Here are some ideas to make the most of your releases with the power of release notes:
Above, we have referred to the different personas apart from ‘real customers’ who could find the release notes valuable. Develop different versions of release notes targeting their needs. For example, Customer support should get to read about the changes that will most likely result in customer queries whereas the Marketing team must be informed about the ‘hot feature’ that your team has just brought in.
Coming up with multiple persona focused variants of release notes is not enough. You also have to optimise the distribution channel for engagement. Only then the release notes will get the eyeballs they deserve. Use various combinations of channels & spoil the customers with sufficient choices. For example, an emailed what’s new announcement for the not so engaged user of your product to an in-app banner to excite the already engaged users. A pdf document for your CTO to a social media announcement for your followers. Possibilities are endless.
You have dedicated marketing copywriters to appeal to your website visitors but the release notes variants are written by the software development team. Well, that’s not fair to say the least! Give as much importance to release notes documents as you do to the marketing collateral & your brand will become alive through these changelogs.
It may sound a little odd but release notes could potentially serve different purposes in the lifecycle of a release. For example, just before a few days of go live date teams can internally circulate pre-release notes & may be immediately after the planning phase, publish a different document that talks about the release commitment.
All in all, it is imperative for the success of your releases, to communicate the upgrades you are bringing in to various stakeholders.
From Planning to Deployment: Decoding the Roles and Responsibilities of an Effective Release Manager
Release management with Jira
Now that we have covered all the basics, it is time to explore the practical aspects within Jira & Confluence.
First, we will start with Jira and learn about key topics that will help in managing the releases in this project management tool loved by software development teams.
We will reiterate that Release & Version keywords are used interchangeably even within Jira & we follow suit in this article.
Turning on releases in your project
If you created a new project in Jira, depending on its type & whether it is a company managed or team managed project – it might happen that the Releases are turned off by default & will have to be explicitly turned on.
Software projects usually come with releases feature turned on by default. Now, we are not certain about this feature’s default behaviour in case of work management projects. That is simply because, Atlassian is making a lot of changes to releases in the recent months & this default behaviour seems to be in a state of flux.
However, the simplest way to identify whether your current project offers the ability to turn on releases is by navigating to the ‘Project settings’ and then looking for ‘Versions’. (Yes, you read that right – it is called ‘Versions’ from the project admin side. Soon you will read what you see from the user side 
).
Here’s a work management project on our instance that is company-managed, it shows the ‘Versions’ screen this way.
Now, here’s another work management project albeit a team-managed one. And, it does not show releases/versions related configuration.
For a software project created as a company-managed one, the switch to turn on/off releases is available under Project settings --> Features. Here’s a snapshot.
At the moment, it seems difficult to predict with certainty whether your newly created project in Jira will have the versions/releases feature or not. If yes, whether it will be called versions or releases. But, we hope you do now know where to look for it.
Create, edit & delete releases
Now that we have turned on releases/versions in your Jira project. It is time to find out more about managing them. For software projects that have the feature turned on, Releases menu would appear in the left hand navigation. Whereas for Work management projects, Versions menu appears under Project settings.
Despite the differences in names of the menu items & their locations, the overall process for managing versions/releases is exactly the same. They have the same set of attributes, namely – Name, Start date, Release date & Description.
Once created, the releases are displayed in a list that could be filtered based on release statuses – viz. Released, Unreleased & Archived. The ability to edit & delete a version is available from this listing screen. There are some additional actions as well.
This is nothing but the status change for that version. It moves a version to the released status or allows you to Unrelease it if it is already released.
Archiving a version makes it ‘inaccessible’ from issue updates. Meaning, no new issues can be added to this version once it is archived. And neither can you remove the issues from an archived release.
As the name suggests, it lets you merge two versions into a single one. Use case here is – imagine one of your recent release was delayed and a new one is already being worked on. If it makes sense, you can merge these two in one & go live with them at once.
Adding & removing issues from releases
It may not be immediately clear, but the easiest way to add a Jira issue to any release or version is through Jira’s default field called – Fix Versions.
That is right, Versions. Which means, one Jira issue could be associated with one or more releases. Case in point could be an Epic that gets released gradually across multiple releases.
If you have the necessary permission (we will talk about this in a minute), you can create a new version on the fly & associate it with the issue immediately.
You can use the bulk issue update action in Jira, if you want to move multiple issues into the same set of versions/releases.
Release hub page
When you click on any one of the release names from the release listing page in Jira, you are navigated to the Release hub page. This is where all the issues included in that release are displayed along with a few other details about them.
You can filter the issues based on Epic, Status category, Warnings & Assignee. You can also dictate what information about the issues is displayed on the screen. However, the fields that can be displayed for issues on this screen are limited.
Release hub page also displays the deployment status along with the code related warnings, assuming you have the necessary integrations in place already.
Ability to view release notes & update the version status is also available from this screen.
fixVersion, affectsVersion & version custom fields
Jira offers the ability to associate releases with an issue in multiple ways. By using the fixVersion field you indicate to Jira that the given issue is part of ‘this’ release. Whereas if you wanted to keep track of bugs or defects that impact the releases you can use the affects version field. Our friends at Praecipio have written this nice piece explaining the difference between fix version & affects version. If you are a team focused on incremental releases, you may want to use Jira workflows to make the fix version field mandatory.
Not only that, you can even create custom fields in Jira that are mapped to releases in your project.
Create releases with names such as Parking lot 1, Parking lot 2 etc and move unplanned issues to such releases. This will ensure that you won’t miss any issues while planning the releases.
JQL functions surrounding releases
Jira has this unique SQL like functionality, called Jira Query Language or JQL. It offers an advanced way of searching issues (tickets or whatever else you call them) in Jira. With JQL functions related to versions, it is easy to search for issues associated with specific versions or with a group of versions that have something in common.
For example, unreleasedVersions() function available in JQL will let you consider all the unreleased versions/releases from a given Jira project. This makes the job of finding relevant information from Jira easier by keeping versions at the centre of your discussion. One can always utilise this JQL reference guide to extract maximum value.
Reports & dashboard gadgets surrounding
Given the importance of agile & incremental delivery, Jira's dashboard gadgets & reports assist you in further embedding the 'release' culture in your team.
While the planning focused gadgets: Issue calendar & Roadmap gadgets show information related to versions, the execution oriented 'Version report' helps you easily see your team's progress towards the completion of a version.
Additionally, you can also use free or paid apps from the Atlassian marketplace to get more gadgets & reports focused on releases.
Native release notes feature
Now, Jira also has an out-of-the-box release notes feature. This can be accessed from the 'Release hub' screen we talked about earlier. Atlassian has been recently updating the 'Release hub' to align it with the concept of 'Progressive delivery'. And in that process they have also enhanced the native release notes feature to support publishing them on Confluence.
However, there are still limitations around the layout, look & feel of these release notes & even the fields to be included from Jira.
Relevant permissions
Natively, Jira does not offer a separate granular permission that dictates the ability to manage versions/releases in a given project. These actions are available to anyone who has the 'Administer project' permission.
To find this permission, navigate to any project's settings & then permissions. The first permission listed will be 'Administer projects'. You can assign this permission to individual users, group of users, project roles & through a bunch of other attributes. Check out the screenshot below.
Release planning & reports app for Jira
Create, edit & delete releases
The default set of fields for a release provided by Jira may not always be sufficient if you are looking to increase maturity of your release management processes. You may want to store additional information about the release such as Release type, Planned release date vs Actual release date, Deployment downtime & more.
Our Release planning & reports app for Jira does this metadata storage part convenient for you. With global & project level custom fields you can dictate what information & of what type, should be required at the time of Release creation or editing.
e.g. screenshot below shows the ability to update additional information about the release such as Release type & Release status from the app’s edit version pop-up.
Release listing
If the default release listing in Jira does not make the cut for you, look no further, we got your back. With the ability to filter releases on any of their attributes, showing up the relevant data points as columns & making the planning process efficient via Calendar & Kanban views (with the power of drag & drop) - our Release planning & reports app for Jira is the one you need.
Check out the gif below.
Release hub
Release planning & reports app for Jira takes the Release hub page to a whole new level. You are able to group the issues based on different fields – default or custom. And you can also dictate the fields that are displayed on the screen.
Check the screenshot below.
Release management with Confluence
Ideas for planning & execution process in Confluence
Confluence is a collaboration focused Wiki that gets along nicely with its sibling Jira. While Jira does an amazing job of creating & maintaining structured information, Confluence can be the place where all plans, discussions & decisions reside.
Confluence can support your team through the following three phases of a software release - Planning, Execution & Retrospectives.
- Planning - Right from creating a long term roadmap in Confluence to inform your releases/versions in Jira to documenting the prioritised epics in Confluence, there is a lot that this wiki tool has to offer.
- Execution - Once the plan is set in motion and the start date for a release is exceeded, it is all about keeping things on track to achieve the planned release date. This can be achieved in Confluence through mid-release & pre-release meetings.
- Retrospectives - And finally, once the release has gone live your team can rely on Confluence to reflect on their performance & identify areas for improvement, celebrate smaller wins and more.
Suitable macros
For all of the above ideas, your best friends are Confluence macros that pull in information from Jira. We discuss some of the macros below along with their utility in the context of release management.
- Jira Road Map - Mind you this is a different macro from Jira Roadmap. This one specifically focuses on displaying upcoming versions for a specified project in Jira. This gadget can be useful on the summary page which acts as a reference for all the upcoming releases in a given duration, say 3 months or so.
- Jira - This is probably the most important macro for release management purposes. Using this macro, one can quickly embed the list of all Jira issues that are part of a certain release. This is easily done with the help of JQL. You will use this macro on the dedicate release discussion page you create in Confluence.
Automate routine tasks for maximum value
Once your release management process is effective, it is time to make it efficient. That is where Jira's native automation lends a helping hand. Seamless integration between Jira & Confluence makes your life so much easier here. Depending on your approach, potentially there could be multiple aspects that one can automate. Below we discuss just a handful of them to give you a sneak peek into the possibilities.
Create versions automatically
Jira’s native automation can help you reduce the administrative overhead associated with release management. For example, you can create a new version automatically on different triggers such as - periodically on a specific day, once a version is released in Jira & more.
Create Confluence pages through automation
Atlassian has recently introduced automation for Confluence. With this, you can now create relevant Confluence pages automatically to ensure crystal clear communication across the board. For example, creating a Confluence page that lists all the agreed upon items from a given version once its start date is met or creating a pre-release meeting note to be used as the discussion agenda.
Release notes automation
With Jira's recently enhanced release notes feature or using any of the release notes apps from the Atlassian marketplace, one can easily automate the entire flow of release notes generation to distribution. The underpinning of automation means it is now much easier to create multiple versions of release notes documents for different personas.
Conclusion
While release management involves multiple moving parts, a thought through and detailed approach can bring excellence to the delivery. With Atlassian making its tools seamlessly connect with each other, release management with Jira & Confluence is the logical next step for teams.