Important: ZenHub has launched a ZenHub Sprints entity separate from GitHub Milestones
Changes made to GitHub Milestones will not be synchronized with Sprints. GitHub Milestones will still exist however we recommend checking out Sprints as they function similar to Milestones with a few added benefits.
Burndown Charts are often associated with Scrum, a development methodology known for incremental releases and a focus on customer requirements. As an agile workflow tool, they help teams meet deadlines more predictably by providing an early indicator of how a project is coming along.
Because they provide a visualization of complete and remaining work, they're also a user-friendly reporting tool for GitHub project management.
Just like kanban boards and Epics, Burndown Charts can help you visualize projects across repositories. In ZenHub, each ZenHub Sprint gets its own Burndown Chart.
Creating Burndown charts in GitHub using ZenHub
Burndown Charts are meant to track velocity during short sprints of work – and as such, they are integrated directly with your GitHub Milestones or ZenHub Sprints. You'll find your team's Burndown Charts in the Reports tab. To build your chart, you'll need to have a start and end date set for your GitHub Milestone or ZenHub Sprint. After choosing a Milestone or Sprint, all the Issues which have been estimated will be shown.
Setting start and end dates for GitHub Milestones
(Note: We now recommend checking out ZenHub Sprints to automatically create and manage Sprints)
To create a Burndown chart you first need to assign a start and end date for your milestone. The due date was already set when you create the Milestone, but the start date of a Milestone is unique to reporting in ZenHub.
Select Edit on the top right of the chart, or click Change to select dates.
Setting start and end dates for ZenHub Sprints
ZenHub Sprints allow you to build automatic Sprint schedules that create and close by themselves. Once you set up your first sprint schedule and duration, we'll automatically create all future Sprints including the start and end dates. Learn more here
With a start and end date selected, you need to ensure there are estimated Issues that are added to the Milestone or ZenHub Sprint. If you haven't yet added estimated Issues to a Milestone or ZenHub Sprint or estimated the Issues within the Milestone, you'll see an empty state. New to estimation and need best practices? Check out our blog post 'Introduction to Burndown Chart in Agile Software Development' where we cover how to estimate in ZenHub.
Adding Issues to your GitHub Milestone or ZenHub Sprint en-bulk
Head back to the Boards tab to organize the Sprint. You can use the multi-action to select multiple Issues to be added to the Sprint, or, estimated if you forgot to estimate an Issue but discussed it as a team.
The Burndown will auto-populate data points as Issues are closed
The Burndown report will be split into 2 sections: Sprints and Milestones. Each page will function the same as the other except Milestones will only show GitHub Milestone data and Sprints will only show ZenHub Sprint data. As you finish Issues assigned to the Sprint, a new data point will appear, "stepping down" in the chart.
Along the middle of the graph is a light-gray, dotted line—This line represents the speed at which you need to be closing or completing Issues within your sprint to complete all Issues you've set out to achieve in the sprint. You can be confident you’ll achieve your goal if your team’s completed work closely aligns to this diagonal timeline.
Defining what is "done" using burn pipelines
By default, Burndown Charts display closed Issues and Pull Requests as data points. You can also customize which pipeline triggers a “burned” task by using the Burn Pipelines dropdown menu. For example, if your development team considers a task complete when it reaches the “Ready for QA” pipeline, they can set that here for a more accurate picture of their priorities and progress.
Creating multi-repo Burndown charts
To create a multi-repository Burndown Chart, you'll need to start by connecting repos in a Workspace. In addition, you also have to make sure the same Milestone, with the exact same name and end date exists across all repos you'd like to track together.
Create the same Milestone across your connected repos using the multi-repo Milestone creator. Learn more here.
You'll then see the connected repositories listed at the top of the chart, and any merged Milestones will appear together as one.
Close out a sprint to complete the Burndown
Close the Milestone at the end of a sprint in the same section where you create the Milestone, under the Issues tab.
On the right of every open Milestone is an option to close. Once closed, you can still filter the Board and view all Issues that went into the Sprint; however, one of the key benefits of closing a sprint is that it provides additional reporting around your team's average velocity.
We encourage teams to close Milestones in the Web App when using cross-repo Milestones to ensure all connected Milestones are closed at once. Learn more here.
Filtering the Burndown: What Milestones appear
Currently, ZenHub Burndown's will be available for the last 10 closed Milestones. If a Milestone is too old, you won't be able to pull up the previous Burndown. If you need to save this information, we request using the print-page functionality of your Browser, or leveraging our 'Export to CSV' option for further analysis and customization
Repo-context Milestone filtering
You'll also notice a new repo-context filter that allows you to toggle between the different connected repos in the Workspace. If you use multi-repo Milestones, you will see the same Milestones appear regardless of which repo you choose. However, if there's repo-specific Milestones, you can toggle between repositories without having to re-navigate to a different entry point in GitHub.
Export your Burndown report
When viewing a Burndown report, you can export the report to CSV to further customize and analyse data. To export your report, navigate to to your Burndown report where there is an Export to CSV option located in the top right of the Report page next to the Report title. The fields included in the export are:
- Total story points
- Completed story points
- Ideal speed at which you should be closing Issues
- Issues completed