Introduction to releases
Release reports help teams manage scope changes across long-term projects and better predict end-dates based on what work is happening.
This helps teams answer important questions, such as: “Can we commit to the entire spec for this project and still hit our Q2 goals?” or “Has the increase in newly discovered bugs over the past few sprints impacted our goal of launching our latest major feature by June 30th?”
Why is this type of information important? Business goals and feature launches often span multiple sprints, involve the coordination of multiple teams, and are impacted by a lot of moving parts within an organization. As a result, teams often spend a significant amount of time trying to predict velocity, end-dates, and the most likely path to success against long-term, multi-sprint goals.
When combined with management of stakeholder expectations, it can be hard to stay ahead of what's on track, what's blocked, and overall, how changes within your team's ecosystem are impacting larger goals and deadlines. Release reports provide visibility into multi-team, multi-sprint goals to alleviate the unknowns that come with planning long-term deliverables. Learn more about getting started with releases below.
What are release reports in Zenhub?
Releases help teams understand progress across different sprints, within a central view. This provides a deeper understanding of scope changes over time to determine if you're on track to hit important goals. As scope changes, the release report dynamically updates to provide predictions around end dates based on the information your team is already putting inside GitHub issues.
A release report in Zenhub allows teams to plan across any repositories in the organization for upcoming deadlines. Using GitHub issues, you can organize a release report around any set of tasks or stories. To get started, head to the Reports tab on the top navigation of any repository.
Creating your first release report
Head to the Releases tab to create your first report. If a Zenhub Board is made up of multiple repositories, when 1 of these repositories is added to the release, the report will automatically appear in all connected repositories.
To create a release you'll need to include:
- A report name
- A start date
- A desired end date
The description is optional, but recommended. Use the description to provide context about the goals or outcomes for the release.
If the repositories in this Workspace belong to other Workspaces as well, by default, the release report will automatically be created in all of the other Workspaces. You can choose to remove certain repositories if you wish:
Once you've created the release, head to the Boards to begin adding issues into the report.
The most efficient way to add issues to your release is by using the multi-select functionality on your Zenhub Board. Once on the Board, leverage the filters to drill-down on the issues you'd like to add to your release and use the select all option on the top left of the Board to en-bulk select the entire view.
If you only need to select a few, click on the avatar to enter multi-select and then select all relevant issue cards. Once you've selected all relevant issues for the current view, select Add to release on the top right of the multi-action bar.
Once created, the report will show two lines: the dark purple represents all estimated issues that were added, and the light purple represents both all estimated issues and all non-estimated issues added.
Below, learn more about how the release will change over time and the different elements that will begin to appear.
Understanding the release report
The release report is made up of two major axes.
On the x-axis is the duration of the release: this is set at first by the start and desired end date. As the predicted end-date changes, the x-axis will also update should the predicted end date go beyond the date you've selected.
On the y-axis is the total amount of story points that make up all estimated and non-estimated issues in the release.
Over time, the release report will have multiple layers and lines that show important information about how you're burning-up towards your goal. The following information is presented:
- Completed issues - estimated and unestimated are shown in the dark shade of purple. As your team completes issues, they'll be plotted on the release report. Each completed issue will be added on the Chart based on the date it was closed. Best practice is to estimate as many issues as possible to get a more accurate report.
Note! Completed issues that do not have an estimation will be assigned an average estimation based on the total estimated scope already in your release. To make your report as accurate as possible, best practice is to estimate all issues in your release.
- Estimated issues will be shown in the medium shade of purple. As issues get added, removed, or estimated within the release, this medium shade of purple will change over time to show the amount of estimated scope that is still to be completed.
- The total scope of all issues is shown in the light shade of purple. All issues within a release that are not yet estimated get assigned an average estimation. Similar to estimated issues, as non-estimated issues get added or removed from the release or otherwise estimated, this light purple will go up or down.
Actual velocity vs. desired velocity and predicted end dates
When you assign estimates to issues, you are making educated guesses at how much work will go into completing a task. Over time, estimation provides insight into your team's projected velocity.
You can track your team's actual velocity on the release report by tracking the dark purple line. Taking into account your team's average velocity, the yellow line will predict your desired velocity.
Actual velocity is calculated by using the closing date of completed issues in the release, both estimated and unestimated.
Desired velocity will take into consideration the following:
- The total scope of the release
- The release's start date
- Your desired end date
Knowing the gap between your team’s actual velocity and the velocity that is required to hit your desired end dates enables more accurate estimates and, as a result, more effective sprints and project planning.
As the gap between your actual velocity and desired velocity changes, the predicted end date will be shown on and below the graph. Keep an eye on this date to have important discussions around scope changes that need to be made within your release.
Changes charted across the release report
When issues are added, removed, completed, or scope is changed, dots will be charted across the release report. Hover over each of these mapped dots to learn more about the changes occurring across issues in the release.
The following changes will be documented across the chart:
- Issues being completed (dots that appear across the dark purple area)
- Estimated issues being added or removed from scope (dots that appear across the medium purple area)
- Non-estimated issues being added or removed from scope, as well as issues that are within the release that get an estimation (dots that appear across the light purple area)
When filtering by label, the same changes are documented, as well as the following:
- issues being added or removed to the entire scope of the release (dots that appear in the light gray area)
- Estimated issues being completed across the entire release, not just those completed by label (dots that appear across the dark gray area)
View the release report by a specific label
If you are leveraging GitHub labels to further organize your issues and pull requests, the release report can be filtered by any label that is assigned to any issue within the release.
Whether you want to drill-down on scope and goals by team, have multiple projects within a release, or need to know how a particular area of work is progressing, use the labels dropdown filter to select a label.
Viewing the release by label provides insights into how particular areas of the development cycle have contributed to a release, such as how many bugs have come within projects being deploying.
Removing issues from scope
In agile development, each sprint reveals new information about your team, product, processes, and speed. Factors outside your control are also bound to come up that impact your team's ability to hit deadlines—a sick teammate, unexpected bugs, newly uncovered edge cases–it happens. With Zenhub releases, you can add or remove issues from the scope of the release to accommodate for changes that occur, which were originally unplanned for.
In the list of issues under the release chart, simply hover over an issue to remove an issue or pull request from scope and select remove from scope. This will automatically re-calculate the velocity and predicted end dates on the report, as well as move all removed issues from the release into a separate list at the bottom of the page.
On the bottom of the report is the Release Activity. In this view you can track scope changes made, including movement of: issues being added or moved during the release period, non-estimated issues getting estimated, changes in estimation to already estimated Issues, or the movement of predicted end dated based on velocity changes.
As issues and pull requests get removed from scope, they'll be bundled below all closed issues in a separate section. Need to add them back to the release? Simply hover and select add back to release
Cross-Workspace connections in the release report
When viewing the bottom of the release report you may also see a heading named issues not in this Workspace.
Issues that are also in this release but are not a part of this current Workspace will be listed here:
Editing or closing the release
After the initial setup of a release, you can edit the core details of the report at any time. This is possible through the Edit release button on the top of the release report page.
This is also where the Close release functionality lives. Close a release once you've completed all work to be done. All closed releases are still accessible through the release search dropdown at the top of the reports section on the Release tab.
Note: It is not possible to delete a release once it has been created. Closing a release will remove it from your Board and filters. This release will only be visible to users scrolling through the list of closed releases in the release report tab.
Export your release report
When viewing a release report, you can export the report to CSV to further customize and analyse data. To export the report, navigate to your release report where there is an Export to CSV option located in the top right of the report page next to the report title:
Questions when getting started with Releases
When should I use Zenhub Sprints vs. a Zenhub Release to track work and progress?
The concept of Zenhub sprints to help teams plan short sprints and organize issues against a single deadline. Zenhub Releases, on the other hand, should be used for long-term business goals, external commitments, or any project work that spans across multiple sprints. Releases also have a single end-date, but allow for grouping of multiple Issues, across various smaller deadlines.
When used together, sprints help teams keep an eye on short-term deliverables and scope related to immediate commitments, while releases help teams get an understanding of how short-term work paired with long-term commitments that have not yet come into scope come together around predicted end dates.
For example, you may have external commitment with a fixed date to deliver a product. If your deadline is the end of Q3, but it is currently only the start of the quarter, your team will have multiple deliverables and sprints within the quarter. As you plan your weekly commitments, leverage sprints to organize work being in the short term, and releases for issues in the backlog for a future sprint.
Leverage a release report to start organizing all Issues related to the external deliverable of your product, even if it is not yet being worked on to get insights into whether your team is burning-up towards your desired launch date as you iterate within your sprints.
What's the difference between GitHub's Releases and Zenhub's Release reports?
GitHub's Releases tab is a central location for teams to package and provide software deployments and release notes for users that leverage their products. Zenhub Releases, on the other-hand, are a powerful reporting tool that allows organizations to track against long-term goals or deliverables across: multiple deployments, teams, repos, and sprints irrespective to code or where issues live within the GitHub environment of the team's organization.
Being an internal team report, they help teams predict project end dates based on scope of work and historical velocity, add burn-up reporting for project managers looking to track work across multiple sprints and teams, and provide everyone on the team a central location to visualize roadblocks and team progress.
We share more best practices in our article on common questions when using epics, sprints, and releases together for project tracking.