# Epics and milestones

> Group a project's tickets into epics, split an epic into milestones, follow its progress, launch its tickets and mark it done.

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](#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](#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](#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](https://docs.bydawn.com/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](https://docs.bydawn.com/missions/).

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](#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](https://docs.bydawn.com/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](https://docs.bydawn.com/cycles/): plan an epic's tickets into the weeks ahead.
- [Planning a feature as an epic](https://docs.bydawn.com/learn/planning-an-epic/): the same steps, worked through on a real feature.
- [Group work into epics](https://docs.bydawn.com/developers/epics/): epics in the API, for developers.

Source: https://docs.bydawn.com/epics-and-milestones/