Release reports

Introduction to Releases

Release reports help teams manage scope changes across long-term projects or milestones 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.Release-Reports-View

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.creating-a-release

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.

Once you've created the Release, head to the Boards to begin adding issues into the report.release-with-no-issues

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.release-with-no-issues

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.adding-issues-to-a-release

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.adding-issues-to-a-release

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.release-report-chart

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
  • release-report-chart

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.release-report-chart

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.release-report-tool-tips

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.release-report-by-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.

release-report-by-label

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.remove-issue-from-scope

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 scopeadding-issues-back-to-scope

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.edit-or-close-release

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.

Release report FAQs

As you work through your first Release, here's a few common questions, best practices, and handy solutions.

I have non-estimated issues in my Release, how does this affect the report?

All non-estimated issues will automatically be assigned an average estimation, as long as at least one issue in the report is estimated. The average estimate assigned to not yet estimated issues is calculated by adding all the estimates on the Release and dividing it by the number of estimated issues in the release (open and closed). number of issues in the Release / total number of estimated issues

What's the difference between an Epic and a Release? When should I use each?

ZenHub Epics area theme of work that contain subtasks required to complete the larger goal. Epics contain issues related in subject, and the scope is flexible. Issues can be added or removed as teams discover more about the project or larger story being completed. Epics are a great way to visualize in list format how a grouping of tasks are progressing across your workflow.

Whereas Releases can be considered as much larger objectives, goals, or projects being worked on that span multiple sprints, perhaps across multiple teams, and touch multiple areas of work. Tracking your Q2 goals? Use a Release. Have a major feature launch that contains 5 or 6 large user stories (which are broken down by Epics, with individual tasks to complete these stories in issues)? A great time to create a Release!

Overall, Epics help you visualize how groupings of stories and tasks come together, while Releases help you work towards major milestones across a much larger set of work.

There is also a significant difference between tracking progress of tasks in Epics and the progress of a major Release. The progress of work assigned to Epics can be tracked issue-by-issue in the Board (teams can see all the issue cards in one central view, including where in the workflow each issues is). Releases, on the other hand, are more high-level, such as when tracking individual issues would otherwise be too much (such as spanning multiple sprints).

When should I use a GitHub milestone vs. a ZenHub Release to track work and progress?

The concept of GitHub Milestones help teams plan short sprints and organize issues against a single deadline. Milestones are helpful for planning sprint work. 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, Milestones 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 GitHub Milestones to organize work being worked on versus that which is still in the backlog for a future iteration. 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 milestones 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.

What's a good time frame for a Release?

The start and desired end dates for Releases should be discussed with your team! In general, here are a few questions to ask yourself as you plan for your first Release: “How will our work come together for this major feature launch at the end of the quarter?” “Do we have work that we know will span multiple sprints?” “Is there a major project we are planning for?”

As you start to visualize your backlog of work, the answer to how long a Release should be becomes much clearer.