Epics and milestones

This page helps you hold a piece of work that’s bigger than one ticket together, from the first ticket to the day it’s finished. By the end you’ll know how to create an epic, split it into milestones, file tickets into them, read its progress, launch its tickets and mark it done.

An epic is a deliverable: a feature, a migration, anything that takes several tickets to finish. Each ticket sits in at most one epic, and an epic belongs to one project. A milestone is an optional phase of one epic, with its own target date and the tickets that land by it, such as “Private beta” before “General availability”. A ticket in an epic either sits in one of its milestones or on the epic directly, under No milestone.

Epics are optional. A project can run without any, and a ticket doesn’t need one.

Open an epic

Choose Epics & Milestones in the sidebar, or press ⌘2. By Dawn opens the project’s first open epic. The entry shows how many epics the project has, and stays greyed out until it has one, so create your first epic from a ticket (see Create an epic).

When the project has more than one epic, a list of them runs down the left of the page, grouped as Ready to close, In progress, Backlog and Done. Choose one to open it, or click into the list and walk it with the arrow keys and Enter. Hide epic list folds it to a thin strip, and By Dawn remembers that choice.

The search in the top bar decides which epics the list holds. Press / to jump to it. It starts on Open, which is every epic not yet marked done, and you can switch it to Ready to close, Backlog, Done or All epics, narrow it with chips such as Label, Launch or Target, or type part of a name. The sort button beside it orders the list by Recently updated, Name, Progress or Target date.

You can also reach an epic from a ticket: choose the epic’s name at the top of a card on the board, or Open epic in a ticket’s epic menu.

Create an epic

You create an epic while you create or file a ticket, because an empty epic has nothing to show.

1. Start a new ticket and choose Epic in its row of properties.

2. Type the epic’s name in Find an epic…. When no epic has that exact name, the menu offers Create epic “…”.

3. Choose it. By Dawn creates the epic and puts the new ticket in it.

The epic starts with only its name. The epic page doesn’t edit an epic’s name, plan or target date, but By Dawn’s agent can, so an epic it creates may already have a plan and a target date.

What an epic’s page shows

The top of the page is the epic at a glance: its name, its lifecycle (see Mark an epic done), a one-line summary taken from its plan, its target date and how many days are left, and how many repos its tickets touch. A ring on the right shows how many of its tickets are complete, as 3 / 8 complete.

Under that, a bar splits the epic’s tickets by board column, with a count for each column, so you can see at once how much is waiting, building, in review or done.

The buttons along the top do the epic-wide jobs:

Button	What it’s for
Insights	Opens the project’s Insights, narrowed to this epic.
Launch epic	Starts the epic’s ready tickets (see Launch an epic).
Mark done / Reopen	Closes the epic, or opens it again.
Copy link	Copies the epic’s URL. Its arrow opens more: Copy ID, Copy URL, Copy name, Copy name as link, Copy epic as Markdown and Copy everything as Markdown, which includes the milestones and tickets.
⋯	Delete epic.

The page has four tabs:

• Overview: the epic’s Plan, its Properties, the pull requests its tickets have opened, and the Milestone rollup, one progress bar per milestone. When the plan has an “Acceptance checks” checklist, the Plan’s heading counts how many are ticked.
• Milestones: each milestone with its tickets, and the tickets with No milestone below them.
• Board: the project’s board, holding only this epic’s tickets.
• Activity: the epic’s history.

The copy commands also have shortcuts while the epic’s page is open and no ticket is: ⌘⌥. copies the ID, ⌘⇧, the URL, ⌘⇧' the name, and ⌘C with nothing selected copies the name as a link. The menu shows each one next to its item.

Milestones

Milestones live on the epic’s Milestones tab. They’re listed in the order you give them, each with its target date, a count such as 2 / 5 and a progress bar. Click a milestone’s header to fold its tickets away.

Add a milestone

1. On the Milestones tab, choose New milestone. The New button on the Overview’s Milestone rollup does the same.

2. Give it a Name, which is required. Target date and Description are optional. The description is for what done looks like in this phase.

3. Choose Create milestone. It’s added at the end of the list.

Rename, reorder or delete a milestone

Every milestone has a ⋯ menu, on the Milestones tab and in the Overview’s rollup:

• Edit milestone changes its name, target date or description. Clear a field and save to remove it.
• Move up and Move down change its place in the order.
• Delete milestone removes it. Its tickets stay in the epic and move to No milestone. The tickets themselves are never deleted.

Move tickets between milestones

On the Milestones tab, each ticket row has a flag button. It opens Move to milestone, which lists the epic’s milestones and No milestone. Pick one and the ticket moves at once, without opening it. The flag only appears once the epic has a milestone.

You can do the same from the ticket itself, as the next section shows.

Put a ticket in an epic or milestone

An open ticket shows where it belongs at the top, as project / epic / milestone:

• The epic is a menu. Choose it, or Add to epic when the ticket has none, to pick an epic or No epic. While the ticket has an epic, the menu also offers Open epic.
• The milestone appears once the ticket’s epic has milestones. Choose it, or Add to milestone, to pick one or No milestone.

Moving a ticket to another epic clears its milestone, because a milestone belongs to one epic. Pick the new epic’s milestone afterwards if it needs one.

When you create a ticket, the Epic button sets both at once: pick the epic, and its milestones open under it for the next pick. The menu lists Recent epics first, then All epics.

On the board, a ticket in an epic carries the epic’s name on its own line at the top of the card, with a thin edge in the epic’s colour. Hover the name to see the epic’s summary, how many of its tickets are complete, and the ticket’s milestone. Click the name to open the epic. To see the whole board split by epic, turn on Epic lanes in the board’s grouping, or press ⌘G (see Board and columns).

Progress

By Dawn works progress out from the tickets every time you look, so it never goes stale. A ticket counts as complete when it’s in the board’s done column. Archived tickets don’t count at all.

• An epic’s progress counts all its tickets, in a milestone or not.
• A milestone’s progress counts only the tickets in it.
• No milestone in the Overview’s rollup counts the epic’s tickets that aren’t in any milestone.

A progress bar stays grey while work remains and turns green at 100%.

Mark an epic done

An epic’s lifecycle shows next to its name:

Lifecycle	When
Backlog	The epic has no tickets yet.
In Progress	It has tickets and some aren’t complete.
Ready to close	Every ticket is complete, but nobody has marked the epic done.
Done	Someone chose Mark done.

Reaching 100% doesn’t close an epic, because more work may still be filed under it. Instead it shows Ready to close, and the page says “Every ticket is complete — mark the epic done to retire it from the epic lists.” When you agree, choose Mark done.

A done epic drops out of the default epic lists, and the sidebar’s entry opens the first open epic instead. Find done epics with the Done or All epics view in the search, or on a phone with Show done epics. Choose Reopen to bring one back. Being done doesn’t depend on progress, so a done epic that gains a new ticket stays done until someone reopens it.

Delete an epic

Choose ⋯ › Delete epic. The confirmation says what happens: the epic’s milestones are deleted, and its tickets stay in the project with no epic. The tickets themselves aren’t deleted, but the delete can’t be undone, so prefer Mark done for an epic that’s finished.

Launch an epic

Launch epic starts By Dawn’s agent on every ready ticket in the epic, meaning each ticket that hasn’t started and isn’t waiting on a blocker. The epic then stays launched: as tickets finish and blockers clear, By Dawn starts the next ones, never with more building at once than you allow. Each ticket runs its own mission, so the steps it goes through are the ones explained in Missions and templates.

1. On the epic’s page, choose Launch epic.

2. Choose the settings:

   • Mode: Build now or Plan + build. Plan first isn’t offered, because a ticket that only plans stops in Review and would hold up the tickets after it.
   • Preset: the mission template or preset every ticket starts from. Your default template comes first, then any other templates, then Auto, Quick, Standard and Thorough. A line underneath says what the choice means, and, for a template, which steps By Dawn will carry out itself.
   • Max at once: how many of the epic’s tickets may be building at the same time, from 1 to 20. It starts at 3.

3. Check the summary, such as “2 start now · 3 start later · 1 already building”, and the tickets that start now.

4. Choose Start 2 now (the button names the number).

You can launch an epic even when nothing can start yet. If every ticket left is waiting on a blocker, or Max at once is already full, the button reads Launch epic and the dialog says when they’ll start. By Dawn starts each ticket once its blockers finish or room frees, and blockers still hold. The button stays off only when every ticket is already under way or done. A project with no repos can’t be launched, because there’s nowhere to build.

While the launch runs, a strip under the epic’s buttons shows it as Active or Paused, with how many tickets are Running, Waiting, Done and Skipped. A skipped ticket is listed with the reason, and you can open it from there.

• Pause stops new tickets from starting. Resume carries on.
• Stop ends the launch. Nothing new starts, and tickets already building keep going.

An epic has one launch at a time, so Launch epic comes back once the current one has stopped or finished.

Note

When the dialog says Staging is off — each ticket’s pull request lands on main on its own., the epic’s tickets ship one by one, as they would if you had started each of them yourself.

Do and don’t

Do:

• Mark an epic done when it shows Ready to close. Until you do, it stays in every epic list.
• Use milestones for phases that have their own date. If an epic has no real phases, leave its tickets under No milestone.
• Set Max at once with your reviewers in mind, because every ticket that finishes building waits for review.

Don’t:

• Delete an epic to finish it. Deleting removes its milestones and takes every ticket out of it.
• Expect a ticket to keep its milestone when it moves to another epic. Pick the new one.

FAQ

Why is Epics & Milestones greyed out in the sidebar?

The project has no epics yet. Create one from a new ticket’s Epic button (see Create an epic), and the entry opens it.

Can a ticket be in two epics?

No. A ticket sits in one epic at most, and in at most one of that epic’s milestones. For work that relates to another epic, add a relation between the tickets instead (see Tickets and sub-tickets).

Does deleting a milestone or an epic delete its tickets?

No. Deleting a milestone moves its tickets to No milestone in the same epic. Deleting an epic deletes its milestones and leaves its tickets in the project with no epic.

My epic is at 100%. Why isn't it Done?

100% means Ready to close. By Dawn leaves the call to you, because more work may still be filed under the epic. Choose Mark done when it’s finished.

Can a launch start the same ticket twice?

No. A launch starts each ticket at most once. If a ticket it started needs another run, start it from the ticket.

Next

• Cycles: plan an epic’s tickets into the weeks ahead.
• Planning a feature as an epic: the same steps, worked through on a real feature.
• Group work into epics: epics in the API, for developers.