Help Center

If you are working on cross-project or cross-team initiatives, it is often hard to know what type of information should be tracked as an Epic or Milestone, or how Releases and milestones are different from each other and when you should use one or the other.

Organizing information within GitHub and Zenhub efficiently from the start will help your team manage initiatives and create an ecosystem of information that can be efficiently kept up-to-date so everyone on the team gets the most accurate picture of progress.

Quick overview: Milestones vs. Releases

Below is a summary of the differences between Milestones and Releases in GitHub and Zenhub. Before each point is a question to ask yourself as you're planning to know whether you should use Milestones or Releases.

• What does your deadline look like? Milestones are used for short-term, iterations of work. Releases are used for long-term, flexible scope, dynamically changing projects and committments.
• Do you want to track progress as it happens or forecast ahead? Milestones help teams track progress within a short time frame. Releases help teams forecast deadlines and delivery dates.
• Do you want to track Velocity for a team, or for a specific deliverable? Milestones are used to track team Velocity over time. Releases track Velocity based on the work being completed within the Release itself.
• Are you estimating work? Both Milestones and Releases are built using estimated GitHub Issues and Pull Requests.

Use Milestones for short time-boxed iterations and fixed scope

(Note: We now recommend checking out Zenhub Sprints to automatically create and manage Sprints)

GitHub Milestones help teams plan short iterations of work and organize issues against a single deadline.

Milestones are helpful for planning time-boxed efforts where there are limited to no scope changes.

Looking to plan long-term projects or initiatives? Use Zenhub Releases. Releases can be used for long-term business goals, tracking scope changes for external commitments, or any project work that spans across multiple sprints or has a long timeline.

GitHub Milestones build Burndowns when used alongside Zenhub Estimates. Teams use Burndown charts within a sprint to visualize if they're on track to get the committed to work done within the sprint. Burndown charts break down your Completed Issues, Open Issues and any Incomplete Issues within the Sprint. Incomplete means that an Issue was completed out of scope of the Sprint or milestone. So an issue completed after the end date of the Sprint.

Completed and Incomplete Issues View

One long-term benefit of using Milestones is that overtime, as Milestones get closed, ZenHub uses the data you're already working with to build the Velocity chart. Velocity can be used to help teams understand how much they can reasonably commit to over time, helping provide clarity to stakeholders or add predictability around work in progress.

Creating a cross-repo Milestone helps teams who track work across workspaces accurately report back on work completed within the time. When a Milestone has the same start/end date and name, the Burndown and Velocity will naturally track work together on the report.

Use Releases to track cross-project goals and keep track of long-term initiatives

If you have a large initiative, need to communicate deadlines to stakeholders, or are long-term planning for features you're going to be launching, look to Releases to help with deadline management and managing a bundle of Issues across multiple projects. Zenhub Release's can be used to manage long deadlines and risk, which give teams a predictable indicator of Velocity along the way.

Unlike Milestones, Releases help teams forecast delivery dates based on continuously evolving requirements. They help with management of long term initiatives because they give teams forecasting abilities that help teams manage risk. By highlighting scope changes, and dynamically updating as Issues get added, removed, and completed, Releases show how scope changes impact deadlines.

Releases can also be built using Issues, Epics, and Pull Requests from every single repository within your GitHub organization. Milestones, on the other hand are repo-specific, making it hard to plan cross-repo.

Releases are best for tracking long-term initiatives because they will dynamically calculate a predicted end date based on how the Issues within the Release are actually being completed. In the image below you can see that based on how fast the work is being completed, the project is a month off-target. Releases provide this type of insight before it becomes too late to manage bottlenecks, roadblocks, or resource allocation challenges.

In addition to actually tracking progress, velocity, and scope, Releases are also a great way to start thinking about how your team incorporates continuous improvement processes to stay agile. 

For example, Releases can help introduce process improvement changes around how your team handles reactionary requests from stakeholders, introduces new ideas and discoveries that comes up during the course of a project, and have more informed conversations about how resources get allocated within your team.

Since teams are able to visualize everything in a project long-term, against the prioritization of those Issues in the Release, you can get not just the projected end date based on your team’s average speed of work, but it becomes easier to have conversations with other individuals around what would need to get sidelined if new work comes up. This opens a discussion around the impact of new work on the expected deadline. 

This provides instant insight into how changes during a Release effect the outlook of other business goals.