# Cycles

> Turn on cycles for a project, plan tickets into them against your velocity, follow a cycle as it runs, and complete it.

This page shows you how to run a project in cycles: fixed-length stretches of work that By Dawn schedules for you. By
the end you'll know how to set a cadence, plan tickets into a cycle, read a cycle's progress, and what happens to
unfinished work when a cycle ends.

A cycle is a numbered, dated block of time, two weeks by default, that belongs to one project. By Dawn keeps the
current cycle and a few upcoming ones created ahead, each starting at midnight on the same weekday in the project's
timezone. A ticket sits in at most one cycle at a time. When a cycle ends, By Dawn freezes a report of how it went and,
if you let it, moves the unfinished tickets into the next cycle. That way the team always knows what it's working
on this cycle, and how much it usually gets through.

Cycles are optional and off for a new project. Workers don't need them, but people planning review time or a
release often do.

## Turn on cycles

Only project admins and org admins can change a project's cycle settings, because the cadence applies to everyone
on the project.

1. Open **Settings › This project › Cycles** and switch on **Use cycles**. By Dawn starts with your browser's
   timezone, and the first cycle is the one running today: it opens on the most recent start day.

2. Under **Cadence**, set:
   - **Duration**: how long each cycle runs, from 1 to 8 weeks.
   - **Starts on**: the weekday every cycle begins.
   - **Cooldown between cycles**: a gap between one cycle's end and the next one's start, **None** or up to 4
     weeks.
   - **Upcoming cycles kept ahead**: how many future cycles By Dawn keeps created, so you can plan further out.
   - **Timezone**: where midnight is for the start day. **Use my timezone** fills in yours.

3. Check **Next 3 cycles**, which shows where the cycles would fall with your settings before anything is saved.
   Then choose **Save changes**.

A cadence change applies to upcoming cycles only. The running cycle keeps its dates, so a change never moves work
that's already under way.

Turning cycles off asks first. Nothing is deleted: your cycles, their reports and every ticket's cycle stay, and
By Dawn stops scheduling new ones. With cycles off, the cycle controls disappear from the app until you turn them on
again.

### Automations

The same card has four switches that decide what joins or leaves a cycle without anyone planning it:

| Switch | What it does |
|---|---|
| **Roll over unfinished tickets** | When a cycle ends, its unfinished tickets move into the next cycle. Off leaves them in no cycle. On by default. |
| **Add started tickets to the active cycle** | A ticket with no cycle that moves into a started column joins the running cycle. |
| **Add completed tickets to the active cycle** | A ticket with no cycle that is completed joins the running cycle, so unplanned work still counts. |
| **Allow Run cycle** | Adds **Run cycle** to the running cycle's page (see [Run a cycle](#run-a-cycle)). |

A ticket that already has a cycle is never moved by these.

## The Cycles page

With cycles on, the project's sidebar row reads **Cycles & Releases**, and `⌘5` opens the
**Cycles** tab. It sits beside **Releases** and **Changelog** (see [Releases](https://docs.bydawn.com/releases/)).

The page lists cycles under **Current**, **Upcoming** and **Past**. Each row shows the cycle's dates, where it
stands against the clock ("4 days left", "Starts in 3 days"), how much is done, and the release it ships in, if
any. The header shows the cadence and, once a cycle has completed, the project's velocity.

**Velocity** is the average amount completed over the last three completed cycles. On a project with estimates
it's counted in points, otherwise in tickets (see [Estimates](https://docs.bydawn.com/estimates/)). Once there's a velocity, every running or
upcoming cycle shows a capacity bar: what's planned into it against that velocity. The bar turns to a warning colour once the plan runs
past a typical cycle's delivery, which is your cue to move work out before the cycle starts rather than roll it
over after.

## Add tickets to a cycle

There are several ways in, depending on where you are:

- **On a ticket**, the cycle sits in the header. Choose it (it reads **Add to cycle** when the ticket has none)
  and pick from **Current**, **Next** and **Upcoming**, or **No cycle**. `⌘⇧C` opens it from the
  keyboard in the desktop app, and `⌘⌥⇧C` in a browser.
- **When you create a ticket**, set **Cycle** in the composer or in quick add.
- **On the board**, select several cards and use **Move to cycle**. You can also filter or group the board by
  **Cycle**.
- **In the cycle planner**, which is built for planning a whole cycle at once.

A card in a running or upcoming cycle shows a small chip with the cycle number, such as C13. If the ticket has
been carried over from earlier cycles, the chip adds ↻×2 (or however many cycles running), so work that keeps
slipping stands out.

Tickets can't be added to or taken out of a completed cycle, because its record is history.

## Plan a cycle

The planner puts the project's backlog beside one cycle, so you can fill the cycle and watch its capacity as you
go. Open it with **Plan next cycle** on the Cycles page (or **Plan current cycle** when nothing is scheduled), or
with **Plan** on a cycle's own page. The cycle menu at the top switches to another running or upcoming cycle.

1. Narrow the **Backlog** with the search box and the epic, assignee and other filters. The backlog holds every
   open ticket that isn't in a cycle, most urgent first. A ticket waiting on another shows **Blocked**.

2. Select tickets by clicking their rows. Shift-click selects a range, and **Select all** takes everything the
   filters show.

3. Choose **Add to Cycle N**, or drag the selection onto the cycle's side. To take tickets back out, select them
   on the cycle's side and choose **Remove**, or drag them back to the backlog.

Every move is saved as you make it, and the capacity bar above the cycle updates at once. Until the project has
completed a cycle there's no velocity to measure against, so the planner shows only how much is planned.

On a phone the planner shows one side at a time, with a switch between **Backlog** and the cycle, and you move
tickets by selecting them rather than dragging.

## Follow a cycle

A cycle's page opens from its row on the Cycles page. The header shows the dates, the time left, and three
counts: **Scope** (everything in the cycle), **Started** and **Completed**, in points when the project uses
estimates. Below it are the tabs:

| Tab | What it shows |
|---|---|
| **Issues** | The cycle's tickets as a board. |
| **Burn-up** | Scope and completed work day by day, with the ideal pace as a dashed line. The first point appears at the end of the cycle's first day. |
| **Breakdown** | Progress split by **Assignee**, **Epic**, **Label** or **Priority**. Choosing a row shows the **Issues** tab narrowed to it. |
| **Release** | The release this cycle ships in, with its progress and readiness. It appears only when the cycle is linked to one. |
| **Tests** | The cycle's test plan, with its pass rate and each item's status, or **Draft a test plan** when it has none. See [Plan testing for a release or cycle](https://docs.bydawn.com/test-plans/). |
| **Report** | A completed cycle's frozen report (see [When a cycle ends](#when-a-cycle-ends)). |

**Insights** opens the project's insights for exactly this cycle's window. On a running or upcoming cycle, **Edit**
changes its name, description and dates. A cycle's days can't overlap another cycle's, so By Dawn refuses dates that would.

### Run a cycle

When **Allow Run cycle** is on, the running cycle's page has **Run cycle**. It starts a worker on each ticket in the
cycle that is ready: not started yet, and not waiting on a blocker. The confirmation lists the tickets first. Each
one moves to Building, and a machine that's busy queues its share. One run starts at most 20 workers, so for a
larger cycle you run it again for the rest. To start one ticket at a time instead, see [Missions and templates](https://docs.bydawn.com/missions/).

## When a cycle ends

A cycle completes on its own at the end of its last day. To end it early, open the running cycle and choose
**Complete now**. Either way:

- **Unfinished tickets** move to the next cycle when **Roll over unfinished tickets** is on, and to no cycle when it's
  off. A ticket counts as unfinished until it's in a completed column, and archived tickets don't count.
- **The report is frozen.** The **Report** tab keeps the numbers the cycle closed with: scope, completed, rolled
  over, and how many tickets were added after it started or removed before it ended. It also has the burn-up, a row
  per assignee, and the tickets behind every count. Moving a ticket later doesn't rewrite it, which is why velocity
  reads from reports.
- **The next upcoming cycle** still starts on its own schedule. Completing early doesn't pull it forward.

For a cycle that isn't linked to a release, **Complete now** asks once and says where the unfinished tickets will
go. Choose **Complete cycle** to confirm.

### Completing a cycle that feeds a release

When the cycle ships in a release that's still open, **Complete now** walks you through up to three steps, because
the unfinished tickets are in that release too:

1. **Review** says what's done and what isn't.
2. **Unfinished work** asks what happens to the unfinished tickets' place in the release. They can move on with the
   cycle to the next cycle and its release (marked **recommended**), hold the release for them, or leave the
   release. A list under **What moves** shows, ticket by ticket, which releases each one leaves or joins.
3. **Release** offers to ship the release now, with its readiness checks. Choose **Complete, don't ship** or
   **Complete & ship**.

A step that has nothing to decide is skipped. The default for step 2, and whether step 3 is offered at all, are
release settings (see [Releases](https://docs.bydawn.com/releases/)). After the close you can undo the release changes for 10 minutes from the
same browser. The cycle itself stays completed.

## Cycles and releases

A cycle can feed one or more releases. When it does, its tickets join the release and follow the cycle, so you plan
the cycle and the release fills itself. The cycle's header shows a **Ships in** chip for each release.

When a running or upcoming cycle isn't linked to anything, its page may suggest the open release dated in or soonest
after its window. Choose **Link** to accept, or **Not now** to hide that suggestion. You can also link cycles from
the release's side, and unlink them from either side. [Releases](https://docs.bydawn.com/releases/) covers both.

## Do and don't

- **Do set the timezone to where the team works.** Cycles start at midnight there, so a zone hours away makes the
  first and last days feel shifted.
- **Do plan against the capacity bar** once you have a velocity. Planning far past it mostly produces carry-over.
- **Don't use a completed cycle to track late work.** Its membership is frozen, so a ticket you finish afterwards
  belongs in the current cycle.

## FAQ

**Can a ticket be in two cycles?**

No. A ticket sits in one cycle at a time, or in none. Moving it to another cycle takes it out of the first.

**I changed the cycle length. Why didn't the current cycle change?**

Cadence changes apply to upcoming cycles only, so work already under way keeps its dates. To change the running
cycle's dates, open it and choose **Edit**.

**Why doesn't the capacity bar show?**

Capacity needs a velocity, and velocity needs at least one completed cycle. Until then the planner shows how much is
planned without a bar.

**What happens to my cycles if I turn them off?**

Nothing is deleted. Cycles, reports and every ticket's cycle stay, and By Dawn stops scheduling new ones. Turning cycles
back on picks up the same rhythm: the next cycle falls where the original cadence puts it, rather than restarting from
today.

## Next

- [Estimates](https://docs.bydawn.com/estimates/): measure cycles in points rather than tickets.
- [Releases and the project changelog](https://docs.bydawn.com/releases/): ship what your cycles finish.
- [Running a cycle with agents](https://docs.bydawn.com/learn/running-a-cycle/): a cycle from planning to close, worked through.

Source: https://docs.bydawn.com/cycles/