Phases, sprints and milestones
What this page is — The rules that relate the three kinds of Roadmap entry — a phase contains sprints and milestones; a task sits in one time box and may contribute to one milestone. What it is for — Reading a Roadmap and a plan without guessing which sprint belongs to which phase, and counting a phase's work without double counting. The problem it solves — Before Planning, phases, sprints and milestones were flat entries with no relationship and no date checks, and a task had a single "milestone" field that pointed at any of the three. Progress rolled up inconsistently and a sprint could quietly run outside its phase.
Routes: Project → Roadmap (create and edit) · /org/tasks/planning?tab=timeline (Structure and Gantt views, reschedule) · /org/tasks/planning?tab=board (the Plan tab: add, create, edit or delete a sprint or phase inside a scenario) · Permissions: the project milestone permission (create, edit, parent, reschedule), View planning (Timeline tab), Manage planning together with the milestone permission (Reschedule…, and creating, editing or deleting a sprint or phase in a scenario)
Module: Planning · Entry points: Roadmap → New milestone drawer · Planning → Timeline · Planning → Plan → Add sprint / Add phase column · Create task / Task detail → Sprint / Phase and Contributes to milestone
1. The three kinds, and the one relationship
| Kind | Has dates | Parent | Holds tasks as | Gets a plan and capacity |
|---|---|---|---|---|
| Phase | Start and end | None — a phase is the top | Time box (directly, and through its sprints) | Yes |
| Sprint | Start and end | A phase (optional) | Time box | Yes |
| Milestone | End date | A phase (optional) | Contribution target | No |
The model is Project → Phase → Sprints + Milestones. Sprints and phases are time boxes that hold tasks; milestones are dated checkpoints that tasks contribute to. The relationship is one level deep: a sprint or milestone may name a Parent phase; a phase can never have a parent; nothing sits under a sprint. Parent and child must belong to the same project. Deleting a phase does not delete its children — they simply lose their parent and appear under Sprints without a phase.
2. Why you would use the hierarchy
- Rollups become honest. A phase's progress counts its own tasks plus the tasks of its sprints, once each.
- Dates check themselves. A sprint that spills outside its phase is flagged the moment it is saved.
- Planning follows it. Ticking a phase in a scenario brings its sprints along; the Plan tab plans one phase's sprints at a time or rolls each phase up with its sprints; the Timeline tab's Structure view lists sprints and milestones under their phase.
- Reports can group by Phase even when a task only names its sprint.
3. Date rules — warn or block
Structural mistakes are always rejected, inline in the drawer:
| Message | Meaning |
|---|---|
parent_must_be_phase — "X is a SPRINT" | You picked a sprint or milestone as the parent |
phase_cannot_have_parent | A phase was given a parent (the picker is hidden when the type is Phase) |
parent_project_mismatch | The parent belongs to another project |
Date containment depends on Project settings → Planning → When a sprint or milestone falls outside its phase:
| Finding | Text shown | Warn mode (default) | Block mode |
|---|---|---|---|
sprint_outside_phase | This sprint's dates fall outside its parent phase. | Saved; toast Saved with warnings | Save rejected |
milestone_outside_phase | This milestone's date falls outside its parent phase. | Saved with warning | Save rejected |
phase_outside_project | This phase's dates fall outside the project's dates. | Saved with warning | Save rejected |
phase_shrinks_below_children | This phase is now shorter than the sprints or milestones inside it. | Saved with warning | Save rejected |
sprint_overlap | This sprint overlaps another sprint in the same phase. | Warning | Still only a warning |
task_outside_timebox | The task's dates fall outside its time box. | Warning chip on the task and on the Planning Plan tab | Task save rejected |
The same findings appear as chips on the Planning Timeline tab, so you can clean a Roadmap up before switching a project to block — see Settings. The rules apply equally to a sprint or phase created or edited on the Plan tab: the scenario checks them against its own version of the Roadmap when you save, and the commit checks them again before writing.
4. A task's two links
Every task has two separate fields in the Create task drawer and in Task detail:
| Field | Points at | Meaning |
|---|---|---|
| Sprint / Phase | A sprint or a phase | When the work happens — the time box that counts it in capacity |
| Contributes to milestone | A milestone | What the work delivers — the milestone whose progress it feeds |
A task may have either, both or neither. Older habits are tolerated: if something still writes a milestone into the Sprint / Phase field, the platform moves it into Contributes to milestone and leaves the time box empty. Both fields cascade to subtasks the way milestone always did — see Subtasks.
On the Planning Plan tab the time box is the column and the contribution is the Milestones rail on the right; dropping a card on a milestone sets Contributes to. The rail's readiness chip (On track, Late · date, n unplanned, No tasks, Done) compares the end dates of the contributing tasks' sprints and phases with the milestone date — see Scenarios and commit.
5. Story points, days and the size scale
A project that plans in days (Settings → Estimation unit) shows and takes every estimate in days — cards, columns, Capacity, the task drawer's Estimated days — converted with its hours per day; hours stay the stored figure, and story points are hidden. The rest of this section is the hours and points chain.
Story Points is an optional, non-negative number on every task. How it turns into hours is set per project in Settings:
- Size scale — labelled rows such as XS = 1 point / 2 h up to XL = 8 points / 32 h (the defaults). A task sized with a label gets that row's points and hours.
- Hours per point — used when a task has points but no size label; blank means derive from the scale.
When a task has points and no hours, Est. Hours (and remaining hours, while untouched) are filled from the points. Typing hours by hand switches the task's Estimate Source to manual and the points stop driving it. Planning scenarios use the same chain: planned hours → points → live remaining → live estimate.
6. How progress and reports count tasks
One rule serves every screen — Roadmap progress bars, Progress reports, the Risk radar, the Report builder and the delivery forecast:
| Entry | Counts |
|---|---|
| Sprint | Tasks whose time box is the sprint |
| Phase | Its own tasks plus every task of its child sprints, each task once |
| Milestone | Tasks that contribute to it |
In the Report builder, Sprint / Phase is the time box, Contributes to Milestone is the target, and Phase resolves a task to its sprint's parent phase (or to the phase itself).
7. Changing sprints and phases while planning
Phases, sprints and milestones live on the Roadmap, but a planner does not have to leave Planning to add, rename, move or delete a sprint or phase. Inside a scenario these changes wait for the commit, exactly like task moves: the Roadmap, other scenarios and the task pickers keep showing the old picture until the scenario is committed, and then the box changes and the task changes are written together.
The Plan tab ends with an Add sprint column (planning by sprints, for the phase in the picker) or an Add phase column (planning by phases), on a draft scenario:
| Part of the column | What it does |
|---|---|
| On the Roadmap, not in this scenario | Lists existing boxes the scenario does not plan yet; Add puts one in the scenario, and adding a phase brings its sprints |
| Create sprint / Create phase | Opens a dialog with Title, Start and End prefilled — the next number and dates right after the last box — and a warning when the dates run outside the phase. Saving adds the box to this scenario with a New chip; it goes on the Roadmap when the scenario is committed |
Each sprint or phase column also has a ⋯ menu: Edit title & dates, Move into a phase…, Undo changes (use the Roadmap's), Remove from this scenario, and Delete on commit (Discard for a box created in the scenario). An edited box shows an Edited chip whose tooltip gives the Roadmap's version; a deleted box leaves the board and is listed under Deleted on commit with Restore. See Scenarios and commit → Edit, move or delete a sprint or phase.
Use Add when the sprint exists but the scenario was seeded without it; use Create when the phase needs one more sprint. The date rules of section 3 apply to the scenario's version: in warn mode a box outside its phase is kept with a warning, in block mode it is refused. When a phase is deleted in a scenario, its sprints stay and lose their phase — as on the Roadmap. If someone changes a box on the Roadmap after you edited it in a scenario, the commit preview warns (timebox_edit_conflict) before your version overwrites theirs; if they deleted it, the commit is blocked (timebox_gone).
A sprint that belongs to no phase is on none of the Sprints views, which each show one phase. The Plan tab therefore names it above the columns — “A sprint is not in any phase, so it is not on this view: Sprint 1 (18 Sep → 1 Oct · 1 task)” — with Show it → (opens Sprints without a phase) and Move into a phase…. The commit preview also warns (The Roadmap already has a sprint or phase with this name) when a sprint or phase the commit creates repeats the name of one already on the Roadmap, so a scenario cannot quietly add a second Sprint 1.
The Roadmap itself still changes boxes at once — it is not part of a scenario. The Timeline tab's Reschedule… saves in the selected scenario; only with no scenario selected does it change the Roadmap directly.
8. The Timeline tab — Structure and Gantt
The Planning Timeline tab shows the selected scenario's plan: its phases and sprints as the scenario has them — created, edited or deleted there — with the project's milestones. The line above the views reads Plan of "<scenario>". Rows carry New (created in the scenario), Edited (hover for the Roadmap's version) and Deleted on commit chips, and show the hours planned against capacity in the scenario (a phase adds up its sprints) and the scenario's goal. With no scenario selected, the tab shows the live Roadmap and its committed plans, as before.
Two views are switched with Structure | Gantt at the top:
| View | What it shows | When to use it |
|---|---|---|
| Structure (default) | An outline of the hierarchy: each phase with its sprints and milestones indented underneath, then a Not under a phase group for sprints and milestones without a parent. Each row shows its kind, dates (a milestone shows Due and its date), status, open and done tasks, a Committed chip with the committed hours against net capacity and the goal when a plan was committed, and any warning chips | Seeing how phases, sprints and milestones relate, and spotting a sprint with no phase |
| Gantt | The same tree on a week scale: phases as bars, sprints as coloured bars and milestones as diamonds underneath, with a red Today line. It opens scrolled to today. A committed pill marks boxes with a committed plan; hover a bar for dates, open and done tasks and the committed plan | Seeing the roadmap in time and which boxes overlap |
Reschedule… (calendar icon) needs Manage planning and the milestone permission. On a scenario it is on every sprint and phase and saves the new dates in the scenario; for a phase, Shift its sprints moves them by the same number of days (milestones and task dates are live data and stay). With no scenario selected it is on phases and changes the Roadmap at once, with Shift sprints and milestones inside and Shift task dates. Open the Roadmap opens the project's Timelines/Milestones tab, where edits apply at once. For example, the Structure view might read Phase 2 ▸ Sprint 4, Sprint 5, ◆ Portal Launch, followed by Not under a phase ▸ Hotfix sprint.
9. Worked example
A project runs Release 3 (1 Oct – 30 Nov) with sprints R3-S1 (1–14 Oct) and R3-S2 (15–28 Oct) under it and the milestone Beta ready (28 Oct). A planner extends R3-S2 to 3 Nov; the phase runs to 30 Nov, so nothing fires. She then shortens the phase to 20 Oct: in warn mode the toast reads Saved with warnings and the Timeline tab's Structure view shows phase shrinks below children on Release 3, with R3-S1, R3-S2 and Beta ready indented beneath it; in block mode the same save would be rejected until R3-S2 is shortened first. A task "Payment retries" is placed in R3-S2 and contributes to Beta ready: the phase counts it once, the milestone's progress moves when it completes. With no scenario selected, she uses Reschedule… on the Timeline tab on Release 3, shifts it two weeks with Shift sprints and milestones inside and Shift task dates on; both sprints, the milestone and the open tasks move by fourteen days in one step. Later, planning by sprints on the Plan tab with Release 3 in the picker, she presses Create sprint; the dialog offers Sprint 3 starting the day after R3-S2 ends with the same two-week length; she renames it R3-S3 and saves. The column reads R3-S3 · New: she plans six tasks into it, while the Roadmap still shows two sprints. When she commits the scenario, R3-S3 appears on the Roadmap under Release 3 with the six tasks in it.
10. Field reference — the Roadmap drawer and Reschedule dialog
| Field | Where | Type | Required | Notes |
|---|---|---|---|---|
| Type | Roadmap drawer | Phase · Sprint · Milestone | Yes | Changing a phase with children to another type is rejected |
| Parent phase | Roadmap drawer | Select of the project's phases, None | No | Hidden for Phase |
| Goal | Roadmap drawer / Planning Goals | Text | No | Committed goals also show on the Roadmap |
| Start · End | Reschedule dialog | Date pickers | Yes | "The end must not be before the start." |
| Title | Create sprint / Create phase dialog | Text, up to 120 characters | Yes | Prefilled with the next number, e.g. Sprint 3 |
| Start · End | Create sprint / Create phase dialog | Date pickers | Yes | Prefilled after the last box; "The end must not be before the start."; warns These dates run outside the phase |
| Shift its sprints | Reschedule dialog (scenario) | Toggle | — | The phase's sprints move by the same number of days, in the scenario |
| Shift sprints and milestones inside | Reschedule dialog (live Roadmap) | Toggle | — | Children move by the same number of days |
| Shift task dates | Reschedule dialog (live Roadmap) | Toggle | — | Open tasks only; tasks of child boxes move only when both toggles are on |
| Sprint / Phase | Task drawers | Select, No sprint / phase | No | Time box |
| Contributes to milestone | Task drawers | Select of milestones | No | Contribution |
| Story Points | Task drawers | Number ≥ 0 | No | "Points cannot be negative" |
11. The admin contract
- Creating and editing phases, sprints, milestones and parents needs the project milestone permission; Planning does not add a second one for this.
- Reschedule… on the Timeline tab needs that permission and Manage planning.
- Creating, editing, moving and deleting a sprint or phase in a scenario needs the same pair, on a draft scenario — and so does committing a scenario that holds such changes (
roadmap_permission_requiredotherwise). Without the milestone permission the column still offers Add for boxes that already exist, and the column menu offers only Remove from this scenario. - The warn/block choice is per project in Project settings → Planning; the default is warn.
12. Don't confuse this with…
- Task Timelines — Gantt of tasks and predecessors; this page is about the containers.
- Task due date — a task can have dates outside its time box; whether that is a warning or an error is the project's choice.
13. Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| The parent picker offers nothing | The project has no phase yet | Create a phase first |
| "parent_must_be_phase" | You chose a sprint as parent | Pick a phase |
| A sprint appears under Sprints without a phase | Its phase was deleted, or it never had one | Edit it and set a parent |
| Saving a sprint is rejected on dates | Project is in block mode | Fix the dates or ask to switch to warn |
| A task shows in a milestone but not in a sprint | It has Contributes to but no Sprint / Phase | Expected — set the time box if it should count in capacity |
| Est. Hours changed after I set points | Estimate Source was points | Type hours to take over manually |
| No Create sprint button on the Plan tab | You lack the milestone permission, or the scenario is committed | Ask for the permission; select or clone a draft |
| A sprint created on the Plan tab is not on the Roadmap | It waits in the scenario until the scenario is committed | Commit the scenario |
| A sprint created from the Plan tab was added with a warning | Its dates run outside its phase and the project is in warn mode | Edit its dates from the column menu, or edit the phase |
The commit is blocked by timebox_gone | A box you edited in the scenario was deleted on the Roadmap meanwhile | Use Undo changes on it, or remove it from the scenario |
| The Timeline opens on today, not on the first phase | The Gantt view scrolls to today | Scroll left, or use Structure |