| 1 | --- |
| 2 | title: The Board |
| 3 | description: The workspace's backlog as it moves, in five stages from Backlog to Done. Each work item's stage follows from what is true of it, its claims, sessions, pull requests and landings, so there is nothing to drag. |
| 4 | --- |
| 5 | |
| 6 | **Board**, in Work's sidebar, at `g1t.sh/<workspace>/-/work/board`, is |
| 7 | the backlog as it moves. Its columns are stages, and a work item's stage |
| 8 | comes from what is true of it: who is on it, its pull requests, where it |
| 9 | has landed. There is nothing to drag. Do the work, and the card moves. |
| 10 | |
| 11 | ## The stages |
| 12 | |
| 13 | | Stage | Holds the work items | |
| 14 | | --- | --- | |
| 15 | | **Backlog** | Open, and nobody is on it. | |
| 16 | | **In progress** | Claimed or assigned, with a live session on it, with a draft pull request, or with a pull request merged that did not close it. | |
| 17 | | **In review** | With a pull request open for review. | |
| 18 | | **Landing** | Landed in some of its target repositories and still missing in others, or with a pull request that closes it merged while a target still misses it. | |
| 19 | | **Done** | Closed as completed in the last 14 days. | |
| 20 | |
| 21 | A work item is in the first stage that holds for it, in the order |
| 22 | **Done**, **Landing**, **In review**, **In progress**, **Backlog**. So a |
| 23 | work item with one pull request in review and another still a draft is |
| 24 | **In review**, and one that has landed in one of its two targets is |
| 25 | **Landing** whatever else is going on. A work item closed more than 14 |
| 26 | days ago leaves the Board, and so does one closed as not planned (a |
| 27 | duplicate, say), since it did not ship. The Work list's **Closed** still |
| 28 | has both. |
| 29 | |
| 30 | ## Which pull requests count |
| 31 | |
| 32 | A pull request counts for a work item when it is for that work item, |
| 33 | when it closes it (`Fixes #12` in its title or description), or when it |
| 34 | is part of it (`Part of #12`). The Board reads each repository's open |
| 35 | and draft pull requests, and those merged in the last 14 days, in every |
| 36 | repository an open work item is linked to. |
| 37 | |
| 38 | - **Merged, and it closes the work item**, but a target repository still |
| 39 | misses it (it merged into a repository that is not a target): the work |
| 40 | item is **Landing** until it lands in every target. |
| 41 | - **Merged as part of it**, or merged with no target left to land in (for |
| 42 | example into a branch that is not the default): the work item stays |
| 43 | **In progress**, since there is more to do before it closes. |
| 44 | - Its card says how many of its pull requests merged in the last 14 days, |
| 45 | such as "1 merged". |
| 46 | |
| 47 | ## How a work item moves |
| 48 | |
| 49 | A typical work item goes left to right as the work happens: |
| 50 | |
| 51 | 1. **Backlog.** Someone files it. Nobody has claimed it, it has no |
| 52 | assignee, no session is on it and it has no pull request. |
| 53 | 2. **In progress.** Someone [claims it](/work/claims-and-dependencies/#claims) |
| 54 | (`g1t work claim 12`), it is assigned, a [session](/work/sessions/) |
| 55 | starts on it, or a draft pull request is opened for it |
| 56 | (`g1t pr create --item 12` opens a draft). A pull request a live session |
| 57 | is on counts too. |
| 58 | 3. **In review.** Its pull request is marked ready for review. |
| 59 | 4. **Landing.** For a work item with targets still to land: its pull |
| 60 | request merged in one target and the others are still to land, or it |
| 61 | merged into a repository that is not a target. A work item whose pull |
| 62 | request lands in its only target, or one with no target, skips this |
| 63 | stage: it closes as soon as it lands. |
| 64 | 5. **Done.** It closed as completed: every target landed, or someone |
| 65 | closed it. See [closing work items](/work/closing/). |
| 66 | |
| 67 | It moves back as well: a claim released or expired with nobody else on it |
| 68 | and no pull request sends it back to **Backlog**, and reopening a work item |
| 69 | clears where it landed, so it goes back to whatever stage its pull |
| 70 | requests and claims put it in. |
| 71 | |
| 72 | ## Reading the Board |
| 73 | |
| 74 | Each column lists its work items most recently changed first, and **Done** |
| 75 | most recently closed first. Each card shows the work item's title, number |
| 76 | and repositories, how many of its pull requests merged lately, and who is |
| 77 | on it: up to three people (its assignees, whoever claimed it, whoever runs |
| 78 | a session on it) and up to two of its live sessions, each followed by a |
| 79 | count of the rest, such as "+4" for seven people. A session with no title |
| 80 | of its own is named by what it is on, such as "On pull request #158". |
| 81 | Choose a card to open the work item. |
| 82 | |
| 83 | A repository that was deleted and can still be restored shows struck |
| 84 | through on its cards, and the Board reads nothing from it. If a |
| 85 | repository's pull requests could not be read at all, the Board says so |
| 86 | above the columns: its work items may stand a column early until it can. |
| 87 | |
| 88 | The Board reads up to 1,000 open work items, the newest first, up to 300 |
| 89 | open and 300 recently merged pull requests in each repository, and up to |
| 90 | 100 work items for **Done**. When there are more, it says so above the |
| 91 | columns, such as "Showing the newest 1,000 open work items." |
| 92 | |
| 93 | The Board follows the work as it happens, without reloading, and checks |
| 94 | again every 30 seconds while a session is live, since a session going idle |
| 95 | sends no event. |
| 96 | |
| 97 | - **One repository's**: filter it with `?repo=<name>`. **Board** on the |
| 98 | Work list filtered to a repository keeps the filter. |
| 99 | - **On a phone** the Board shows one stage at a time, with a button for |
| 100 | each and how many it holds; the address keeps it as `?stage=landing`. |
| 101 | - **In the phone app**, **Board** at the top of Work shows the stages one |
| 102 | under another, with a chip for each to show one alone. It reads only |
| 103 | open pull requests for now, so a work item whose pull request merged |
| 104 | without closing it is where its claims and sessions put it. |
| 105 | |
| 106 | **New work item** is on the Board too. |