Plan releases with milestones and versions

You will learn how to plan date-based milestones, project versions, release contents, and fix/affects version tracking.

Before you begin, read Epics, initiatives, milestones and versions.

1. Choose milestone or version

Use a milestone when the key question is date readiness across one or more projects.

Use a version when the key question is what ships in a specific project release.

Many teams use both:

A milestone for the overall launch date.
Versions for project-specific release contents.

2. Create a milestone

Open Milestones.
Select New milestone.
Enter a Name, such as v1.0 Launch.
Add an optional Description.
Set the Target date.
Select Create milestone.

Open milestones appear under Open. Shipped milestones appear under Shipped.

3. Add issues to a milestone

When creating or editing an issue:

Set Milestone.
Choose the open milestone.
Save the issue.

The issue appears in the milestone's Issues in scope list.

Use milestones for issues that must be ready by the same target date. Avoid adding unrelated work just because it is nearby on the calendar.

4. Review milestone progress

Open a milestone to review:

Name, target date, and shipped date when present.
Description.
Progress bar.
Lifecycle pill: On track, Overdue, or Shipped.
Issues in scope.
Rollup filters and sort.

Milestone progress uses estimates when available, otherwise issue counts.

5. Ship or reopen a milestone

From milestone detail, open the actions menu.

Use:

Edit to update name, description, or target date.
Ship to mark the milestone shipped.
Reopen to reopen a shipped milestone.
Delete to remove an accidental milestone.

Only ship a milestone when the team agrees the target has shipped or no longer needs active tracking.

6. Create a version

Open the project.
Select Versions from the project navigation.
Select New version.
Enter a Name, such as Mobile App 3.0.
Add an optional Description.
Select Create version.

Unreleased versions appear under Unreleased. Released versions appear under Release history.

Use Search versions when the project has many versions.

7. Use fix and affects versions

When creating or editing an issue, set:

Fix version for the release where the fix or work should ship.
Affects version for the release where a bug, regression, or behavior was observed.

Examples:

A bug found in 2.4.0 and fixed in 2.4.1 should use Affects version 2.4.0 and Fix version 2.4.1.
A new feature planned for 3.0 should use Fix version 3.0 and usually no Affects version.

8. Review version progress

Open a version to review:

Version name.
In development or Released status.
Description.
Progress bar.
Issues in scope.
Rollup filters and sort.

Version progress uses estimates when available, otherwise issue counts. Version rollups include done work by default so released contents remain visible.

9. Release or reopen a version

From version detail, open the actions menu.

Use:

Edit to update name or description.
Release to stamp the version as released.
Reopen to move a released version back into development.
Delete to remove an accidental version.

Reopen a version only when the release was marked too early or the team needs to continue tracking it as unreleased.

10. Run a release readiness review

Before shipping a milestone or releasing a version, check:

Are all required issues attached?
Are critical bugs fixed or intentionally deferred?
Are unresolved issues assigned and visible?
Are fix versions and affects versions accurate?
Are release notes or customer-facing changes represented?
Is the target date or release name still correct?

11. Keep release data useful

Healthy release tracking depends on regular cleanup:

Remove issues that no longer belong.
Move deferred issues to a later milestone or version.
Keep affected versions accurate for bugs.
Use descriptions to explain release goals.
Ship or release only when the team is ready to make the record historical.