# Tickets and sub-tickets

> Create a ticket, read and change it in the ticket view, break it into sub-tickets, link it to other tickets, and follow its comments and activity.

This page shows you how to create tickets and work with them in By Dawn. By the end you'll know how to file a ticket
quickly or with every property set, what each part of the ticket view is for, and how to break work into sub-tickets
and link it to other tickets.

A **ticket** is one piece of work on a project's board, and it always sits in exactly one column (see [Board and
columns](https://docs.bydawn.com/board-and-columns/)). It holds what you want done, the properties that plan it, and everything that happens to it
afterwards: the worker's plan and pull requests, comments, and a record of every change. A ticket can have a parent,
which makes it a **sub-ticket**, and it can be linked to other tickets that block it or relate to it.

## Create a ticket

The fastest way in is the create bar at the bottom of the board. It has three sizes, and `Esc` steps
down one size at a time:

- **Minimized**: a thin strip reading **What do you want to build?**. Click it, or press `⌘N`, to
  open it.
- **Expanded**: one line. Type a title and press `Enter` or choose **Add**.
- **Advanced**: the full composer, with a description and every property. Choose **Advanced**, or press
  `⌘⇧N` on the board. **Simple** takes you back to one line.

`⌘N` works from anywhere in the project: off the board, it takes you to the board and opens the bar. In
a browser tab the browser keeps `⌘N` for a new window, so By Dawn uses `⌘⌥N` (and
`⌘⌥⇧N` for the full composer) instead. The bar keeps what you've typed if you leave it, even across
restarts.

A ticket made from one line lands in the backlog column with **Medium** priority, and By Dawn opens it so you can carry
on. To put a ticket straight into a particular column, hover over that column's header and choose **Add to column**
(the **+**). The bar then shows the column's name until you clear it.

### Use the full composer

1. Open the composer with **Advanced** or `⌘⇧N`.

2. Write the title. Press `Enter` to move to the description, and add the detail a worker needs:
   acceptance criteria, links and constraints.

3. Set the properties you want with the row of buttons under the text. Each button shows its value, or its name
   when it's unset (see [The properties](#the-properties)).

4. Attach files if they help. Use the paperclip (**Attach files**), drop them on the composer, or paste them.

5. Choose **Create ticket** (`⌘+Enter`). To file several in a row, open the arrow beside it and choose
   **Create and add another** (`⌘+⇧+Enter`), which keeps the composer open with the same properties.

The button beside the paperclip shows the model and effort a worker will use. Change them there only if this ticket
needs something different, because a ticket you leave alone follows the project's defaults. Once the worker starts,
they're fixed for that run.

In the By Dawn desktop app the composer also offers **Draft it**, which writes a title, description and plan from your
idea, and **Grill me**, which asks you the questions your repo can't answer before it drafts.

If the project has no repo yet, the create bar says **Add a repo first — tickets need somewhere to run** and offers
**Add a repo** instead. A worker clones the repo a ticket targets, so a ticket with no repo would have nowhere to run.

### The properties

| Property | What it's for |
|---|---|
| **Status** | The column the ticket starts in. Left unset, it lands in the backlog column. |
| **Priority** | **Urgent**, **High**, **Medium**, **Low** or **No priority**. New tickets start at **Medium**. |
| **Epic** | The epic the ticket belongs to, and then one of that epic's milestones. You can create an epic from here by typing a name that doesn't exist yet. See [Epics and milestones](https://docs.bydawn.com/epics-and-milestones/). |
| **Cycle** | The cycle the ticket is planned into. Shown only when the project uses cycles. See [Cycles](https://docs.bydawn.com/cycles/). |
| **Labels** | Any number of the organization's labels. |
| **Estimate** | How big the work is, on the project's scale. Shown only when the project uses estimates. See [Estimates](https://docs.bydawn.com/estimates/). |
| **Assignee** | The member who owns the ticket, or **Unassigned**. |
| **Team** | The team that owns the ticket, or **No team**. It starts on your own team when that team works in the project, otherwise on the project's default team. Shown only when a team works in the project. See [Teams](https://docs.bydawn.com/teams/#own-tickets-by-team). |

## The ticket view

Click a card on the board to open its ticket. `Esc` closes it and takes you back to the board.

The top of the ticket says where it belongs and where it stands:

- **The breadcrumb**: the project, then the epic and milestone. Click either to move the ticket to another one, or
  choose **Add to epic** or **Add to milestone**. Moving the ticket to another epic clears its milestone, because a
  milestone belongs to its epic.
- **The ID and status**: the status is a menu of the project's columns, so you can move the ticket from here as well
  as from the board.
- **Chips beside the status**: the cycle (**Add to cycle**, or `⌘⇧C` to open it, `⌘⌥⇧C`
  in a browser tab), the estimate (**Add estimate**), the release (**Add to release**, when the project has
  releases), and the repos the ticket works in. Each chip shows only when the project uses that feature.
- **Badges**: **Blocked by** with the first open blocker's ID, when another ticket is holding this one back.
- **Copy link** and **Actions**: the arrow beside **Copy link** copies the ticket's ID, title, branch name, or the
  whole ticket as Markdown or as a prompt. **Actions** has **Make this recurring**, **Schedule follow-up…**,
  **Archive** and **Delete**.

The title follows. Priority shows as bars beside it (nothing shows for **No priority**), and the labels are listed
under it. To rename the ticket, choose **Edit title**. In a project that a team works in, the header also has the
ticket's team: choose it to pick another team or **No team**. Only the team changes, never the ticket's ID.

The repos chip reads **All repos** until you narrow it. Open it to pick from **Repos this ticket works in**. A repo
that already has a pull request on the ticket can't be removed, and a ticket keeps at least one repo. A running worker
picks up added repos on its next run.

Under the title, **Details** shows who the ticket is assigned to and who created it. Open it to change the
**Assignee** (**Assign to me** is at the top of the list) and to see the **Creator**, along with the time and tokens
the ticket has used so far. A ticket that came in by email, from a chat channel or from an import names where it came
from instead of a member.

### The sections

Below the header, the ticket is a column of sections. A section with nothing in it folds down to its title.

| Section | What it holds |
|---|---|
| **Description** | What you asked for. Choose **Edit** to change it (`⌘+Enter` saves) and **History** to see earlier versions and restore one. |
| **Plan** | The worker's plan once it writes one: the outcome, the **Acceptance checks** it works to (tick them off here), touchpoints, constraints and open questions. |
| The mission | The steps the ticket goes through while By Dawn works on it. See [Missions and templates](https://docs.bydawn.com/missions/). |
| **Branch** | The branch a worker uses in each repo. See [Branching and CI](https://docs.bydawn.com/branching-and-ci/). |
| **Pull requests** | The pull requests the work opened, grouped by repo. |
| **GitHub issues** | Issues linked to the ticket. See [GitHub issues](https://docs.bydawn.com/github-issues/). |
| **Artifacts & previews** | Files, screenshots and previews the work produced. |
| **Linked work** | Blockers, sub-tickets and other links. See below. |
| **Activity** | Comments and the record of everything that happened. See below. |

Beside the ticket is the worker's side, where you start a run and follow it. A ticket can't start while another
ticket blocks it. To start work, see [Missions and templates](https://docs.bydawn.com/missions/).

## Break work into sub-tickets

A sub-ticket is a smaller piece of a bigger ticket. Its ID is its parent's with a number on the end, so the sub-tickets
of `SAW-36` are `SAW-36.1`, `SAW-36.2` and so on.

1. Open the parent ticket and find **Linked work**.

2. Choose **Sub-ticket**. A new row appears with the next ID already filled in.

3. Type a title and press `Enter`. Press `⇧+Enter` instead to create it and start the next
   one straight away, and `Esc` when you're done.

The **Sub-tickets** group lists each one with its status, and the section's header counts them in words, for example
**1 of 3 sub-tickets done**. A sub-ticket counts as done once it's in the completed column. The group's note,
such as **SAW-36 → Review when all done**, says where the parent goes once every sub-ticket is finished.

Sub-tickets don't get cards of their own on the board, which keeps a broken-down ticket from filling a column. The
parent's card carries them instead: it shows a count such as **1/3 subs**, and hovering it lists each sub-ticket.

A sub-ticket's own view says **Sub-ticket of** with the parent's ID, title and progress, and **Back to parent** opens
the parent. To take a sub-ticket out of its parent, hover its row in the parent's **Linked work** and choose **Move
out**. It becomes an ordinary ticket and gets a card on the board.

## Link tickets

Links say how two tickets depend on each other, without making one part of the other.

1. In **Linked work**, choose **Link**.

2. Search for the other ticket by its ID or title.

3. Pick the kind of link from the row at the bottom, or press `Tab` to cycle through them. The line above
   the row spells out what you're about to create, such as **SAW-41 is blocked by SAW-12**.

4. Press `Enter` or click the ticket.

| Link | What it means |
|---|---|
| **Blocked by** | The other ticket has to be finished first. This is where the picker starts, because it's the one with a scheduling consequence. |
| **Blocks** | This ticket has to be finished before the other one. |
| **Related to** | The tickets touch the same thing. Nothing waits on anything. |
| **Duplicate of** | This ticket asks for the same thing as the other one. |

Open blockers are listed first, under **Blocked by**. Everything else is under **Other links**, with the kind of link
after the title. While a blocker is open, the ticket can't start a mission, run or terminal, and its card on the board
says **Blocked by** with the blocker's ID. Once the blocker is completed or archived it stops holding the ticket back.
It moves to **Other links**, marked **was blocking**, so the history isn't lost.

You can also link to tickets in other projects, when an admin allows it in
**Settings › This project › Cross-project links**. The picker then searches those projects too as you type.
To remove a link, hover its row and choose the **×**. That removes the link and nothing else.

## Comments and activity

**Activity**, at the foot of the ticket, is one running record of the ticket. It holds the comments people and the
worker leave, the worker's runs, changes to the ticket's properties, and its pull requests, oldest first. The filters
at the top narrow it to **Comments**, **Activity**, **Changes** or **PRs**, each with its count. While a worker is
running, the record ends with **Now · live run**.

To comment, write in the box at the bottom and choose **Comment**. Type `@` to mention a member, and attach files with
the paperclip. On a comment you can:

- reply to it (replies are one level deep)
- react with an emoji
- copy a link straight to it
- edit or delete it, if you wrote it. Org admins and owners can delete anyone's comment. Deleting a comment also
  deletes its replies, and By Dawn asks you to confirm.

## Archive or delete a ticket

Both are in the ticket's **Actions** menu, and both are in the bar that appears when you select cards on the board.
**Archive** takes the ticket off the board but keeps it, and the board's **Archived** view still shows it.
**Delete** removes the ticket straight away, without asking first, so archive anything you might want back.

## Do and don't

- **Do** put the detail a worker needs in the description, because the worker starts from what the ticket says.
- **Do** use **Blocked by** for real ordering, because a blocked ticket can't start. Use **Related to** when nothing
  has to wait.
- **Don't** create a sub-ticket to say "this depends on that". A sub-ticket is part of its parent's work. A
  dependency between two pieces of work is a link.

## FAQ

**Why don't I see my sub-tickets on the board?**

The board shows only top-level tickets. Each parent's card carries a count of its sub-tickets, and hovering the count
lists them. Open the parent and look under **Linked work** to work with them.

**Why can't I start a worker on this ticket?**

Check the header for a **Blocked by** badge. A ticket with an open blocker can't start until the blocker is completed
or archived, or until you remove the link.

**Why are the Cycle and Estimate buttons missing from the composer?**

They appear only when the project uses cycles or estimates. A project admin turns them on in
**Settings › This project › Cycles** and **Settings › This project › Estimates**.

**Can I get a deleted ticket back?**

No. Delete removes the ticket. Archive it instead if you might need it again, and find it later with the board's
**Archived** view.

## Next

- [Board and columns](https://docs.bydawn.com/board-and-columns/): where tickets sit, and how they move.
- [Missions and templates](https://docs.bydawn.com/missions/): what happens once an agent starts on a ticket.
- [Epics and milestones](https://docs.bydawn.com/epics-and-milestones/): group tickets into a bigger piece of work.

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