Help Center

You've set up your workflow on the Board by customizing the pipelines, defined an introductory label style guide for your team to use, organized Issues into the correct pipelines, grouped work together within Epics, and got acquainted with the concept of Milestones in GitHub.

Now, you're ready to define your milestone in Zenhub

Important questions to answer before planning with GitHub Milestones

How much work can we actually tackle? Can we really ship all this work in the next two weeks? What Issues can we potentially remove from scope? All questions that your team should tackle before sprint planning. But how do you get the answers to these questions?

For your first few iterations, the best way to answer these questions is to talk to your team and have open conversations about the complexity of work you'd like to complete, as well as make sure to tackle work within upcoming critical deadlines that must be completed.

Deciding what goes into your Milestone

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

To figure out what Issues should be added to a GitHub Milestone, you need to have a healthy product backlog.

That means your Issues should have:

• Estimates that you and your team decide on together
• A user story that addresses the who and why of a task, plus any requirements. Don't worry about adding too much detail yet – you’ll discover more information as soon as you start your Milestone
• Priority according to the Issue's business value

Learn more below about how to create Milestones in GitHub that follow this best practice criteria.

Creating your first milestone

To create your first milestone, head to the Issues tab within the repository where your team is working. On the top right, left of the search is the Milestones tab.

On this page, select the green New Milestone button to begin.

Choose a due date for your Milestones that aligns with the end of your work iteration. A rule of thumb to decide how long a milestone should be if you haven't ever measured work in time-boxed durations is to ask yourself if you can get a new feature or enhancement the team is working on through your entire development cycle within the timeframe you're creating.

2 weeks is the most commonly used timeframe.

If 2 weeks seems like too short a timeframe, it's worth taking a look through your Issues and asking yourself if they are too big to tackle. Breaking down work into smaller chunks not only improves the likelihood they'll be shipped, but also eliminates the amount of potential bugs that can postpone a release.

Once the Milestone is created, it's time to add Issues to your sprint! Head back to the Boards tab to get started.

Your first sprint planning meeting

Now that you have your sprint defined as a GitHub Milestone, you're ready to plan what work will be committed to within the sprint. One thing to keep in mind as you prepare for a sprint is that no team ever has all the information needed to move forward flawlessly—dependencies, conflicts, or the urgency of certain bug fixes that might come up... All of this is unplanned work.

Uncovering as many of these what-if scenarios can be uncovered in a planning session, also known as sprint planning. Having a quick conversation before kicking off your first sprint is a platform for discussion.

Adding user stories and tasks to your Milestone

In GitHub, once you've added Issues to a Milestone, they can be considered part of a sprint backlog.

One helpful way to visualize what is in your product backlog and what is part of your sprint, but not yet in progress is to create a Sprint Backlog pipeline.

A Sprint Backlog is different than a product backlog—Issues in your backlog pipeline without a Milestone are your ‘product backlog’ – these are things you’ll eventually tackle but aren't part of your next immediate Sprint of work. A Sprint Backlog are all Issues your team has committed to accomplish in the next 2 week timeframe (or the timeframe you use to define your own iterations).

Similar to moving Issues around your Board en-bulk, use the multi-action functionality on the Board to add all the relevant user stories and tasks to your upcoming sprint. Click on the avatar of all the Issues you want to add to the sprint and select Set Milestone on the multi-action bar.

As work gets picked up by your team from the Sprint, move these Issues to the In Progresspipeline to visually signal to the rest of the team they're actively being worked on.

Once all relevant work is put into your newly created Milestone, it becomes easy to filter your Board by what the team is focused on for the next few weeks. Using the Zenhub Board filters, you can drill-down by Milestone to see only those Issues within the sprint and where in your workflow they are. This allows your team to have focused conversations around progress, blockers, and deadlines.

Estimating issues in your sprint

In GitHub, once you've added Issues to a Milestone, they can be considered part of a sprint backlog. Within a sprint, it's also important to estimate the complexity of the Issues your team is going to tackle.

Estimating the complexity of each Issue relative to the other Issues you're committing to within the sprint provides valuable reporting metrics and provides a much more educated guess at your team’s projected velocity over time.

By default, ZenHub comes pre-loaded with 8 default story point estimates: 1, 2, 3, 5, 8, 13, 21, and 40.

Any Issue that you want to estimate with a 21 or higher, can be considered potentially too complex. If your team is assigning anything a 21, consider breaking down tasks into smaller chunks. Smaller tasks are more likely to be finished with a sprint not just because they're smaller, but because they are more focused. The smaller the task, the more concrete you can be with provided the right details and edge cases to what is being delivered.

Read about more estimation best practices in the full guide to software estimation located here.

To add story point estimates to your sprint Issues, you can use the sidebar of any Issue to assign an estimation point.

Or, you can use the multi-select functionality on the Board to assign estimation to Issues from one central view.

Story points are added to the bottom left of all Issue cards on the Board. This is a great way to visualize the complexity across all Issues you've committed to within the sprint.

Milestones and estimates together help you get a clear picture of average team velocity. Learn more about Velocity charts here.