Projects, tickets and the queue
draftA project
Section titled “A project”A project is the work around one product. It is owned by the person who creates it and shared by invitation.
A project starts from a repository that already holds code, or from a tech spec: then Pitwall files its first ticket, KEY-1, whose run creates the repository from your runner, scaffolds it and opens a pull request you merge (Creating a project).
| A project has | For example |
|---|---|
| A short key, which names its tickets | PG, so tickets read PG-142 |
| One or more GitHub repositories, in the order their pull requests go out | An API before the app that calls it |
| The runner labels its jobs need | linux, or macos and xcode |
| A build and a test command | Run by the gate after implement |
| Where it is tested by hand | One line or a link, shown on every manual test checklist |
| Members, each with a role | Owner, member or viewer |
Tickets
Section titled “Tickets”| Type | Is |
|---|---|
| Bug | Something broken, often with screenshots |
| Feature | A small change or addition |
| Question | A research question |
| Project | KEY-1 of a project created from a tech spec, filed by Pitwall only |
Bugs and features go through the pipeline; a project ticket through the one-step project pipeline (Pipeline steps). A bug’s or feature’s pipeline starts when someone presses Start pipeline, never by itself when the ticket is filed; a project ticket’s starts with the project.
One ticket at a time
Section titled “One ticket at a time”Each project has one slot. The ticket holding it is the only one of that project whose steps run, whoever filed it and whichever runner is free. The others wait their turn, oldest first.
The steps share the runner’s checkout and the ticket’s branch, so two tickets running side by side would step on each other.
| While the ticket | The slot |
|---|---|
Waits on a person in enrich or plan |
Is released: no code is written yet. Once answered, the ticket queues again at the back |
Has reached implement |
Is held until the ticket is done: its manual tests resolved and its pull requests merged or closed |
A queued ticket names the ticket it waits for, on the board and on its own page.
While a person works the project from a terminal, they can mark it worked by hand: the slot is given to nobody until they release it.
Where a ticket runs
Section titled “Where a ticket runs”By default, each step of a ticket goes to any runner whose labels match the project and that has room. A ticket’s author may pin it to a runner label, such as linux, or to one runner.
The ticket’s branch is pushed after every commit, so one step may run on a different machine than the step before. The one exception is a step that asked a question: its answer continues the same session, on the runner that asked.
A run’s states
Section titled “A run’s states”| State | Means |
|---|---|
| Queued | Waiting for the project’s slot |
| Running | A step is queued, running, or paused by a usage limit |
| Awaiting answer | A step asked a person and waits for the answer |
| Blocked | A limit was reached, or a machine failed the same step three times. Waits for a person to resume it |
| Awaiting release | Every step passed. The run waits on manual tests and its pull request |
| Done | Its pull requests were merged or closed, or a person closed a run that had none |
| Cancelled | Someone cancelled it |
A ticket whose run is done is not started again: more work on it is a linked bug or a new ticket.