70 lines
4.4 KiB
Markdown
70 lines
4.4 KiB
Markdown
# Playbook 08 — Small fixes
|
|
|
|
**Trigger.** One issue in one repository, small enough to build in about an hour: a bug with a known cause,
|
|
a missing check, a wording, a playbook or design edit. Anything larger, or anything that needs a change in a
|
|
second repository first, is a feature and follows [playbook 07](07-feature-branches.md).
|
|
|
|
**Related issues in one fix.** A small fix may cover two or three related issues when they are in the same
|
|
repository, mostly in the same module, and together still fit in about an hour: they touch the same files, or
|
|
one would be wrong or unsafe without the other (switching a clipboard's history on before its history tool stops
|
|
handing out what was copied). Each issue is named in the commit and the pull request and moved to `fixing`,
|
|
and each is resolved on its own once the fix is delivered. More issues, a second repository, or more than an
|
|
hour is a feature.
|
|
|
|
**Who runs it.** Anyone who writes code, engineers and agents alike.
|
|
|
|
## The aim
|
|
|
|
A small fix spends its time on the fix, and runs the long part once: **one review, one push, one check run,
|
|
one delivery**. Everything before the push is local and fast.
|
|
|
|
## Steps
|
|
|
|
1. **Read the issue and the code it names** (the session's own model, or one read-only agent on the smaller
|
|
model answering exact questions with file:line). If a design question is open, it is settled before any
|
|
code is written: on the issue, through the knowledge base, or by the operator. A fix that turns out to
|
|
need a decision or a second repository stops here and becomes a feature.
|
|
2. **Move the issue to `fixing`** with `by` as who@node.
|
|
3. **Build on a local branch** `fix/<issue>-<slug>`, in a worktree of its own branched from `main`. Write the
|
|
test that fails today first; make the change; keep `gofmt`, `go vet` and the unit tests of what changed green
|
|
(each well under a second; never a merge check or a database locally: how-we-build §5, ADR 0391).
|
|
Commit, naming the issue. For a playbook or design edit, run the repository's own checks (in hq,
|
|
`sh merge-check.sh`).
|
|
4. **One review of the local commit, before anything is pushed** (a reviewer that did not write it, larger
|
|
model; at most 3 rounds, as playbook 07; from round 2 only what is wrong). The reviewer's findings go back to the same agent that wrote the fix, continued by
|
|
its id, so the fix keeps its context. A playbook or design edit of a few lines may skip the reviewer: the
|
|
operator's word on the pull request is its review.
|
|
5. **Push the branch, try it, then open the pull request.** `mesh-controller.try` with the repository and the
|
|
branch runs the merge check in the check's own toolchain before any status is set; open the pull request
|
|
only once it passes. A local run never stands in for it: the check's containers carry other tools than the
|
|
nodes (a test that called util-linux `flock -E` passed on a node and failed on BusyBox's in the check). The
|
|
forge's merge checks run the integration tests. A failed check
|
|
goes back to the same agent with the failure, and the reviewer reads only the change it makes.
|
|
6. **Mark it ready** (`mesh/ready` and `ready at <full sha>`) once the operator's word is given; mesh-delivery
|
|
merges it when its checks pass.
|
|
7. **Follow its delivery plan to done** (`mesh-controller.plans` with `wait` and `until: done`), prove the fix on
|
|
the mesh (the symptom gone, measured), and resolve the issue with `located-in` and `fixed-by` the same hour.
|
|
|
|
## Bounds
|
|
|
|
| Waiting on | Bound | Past the bound |
|
|
|---|---|---|
|
|
| building the fix | 1 hour | it is a feature: stop and plan it under playbook 07 |
|
|
| the review | 15 minutes | ask the reviewer where it stands |
|
|
| the merge check | 15 minutes | read `mesh-controller.queue` and the check's log |
|
|
| the merge after ready | 5 minutes after the checks pass | read `mesh-delivery.show` for the delivery |
|
|
| the delivery plan | its class's budget (`mesh-delivery.times`), at most 30 minutes | read `mesh-controller.plans`, then `mesh-delivery.stalled` |
|
|
|
|
A wait past its bound is said to the operator at once, with what is being done about it.
|
|
|
|
## Models
|
|
|
|
The fixing agent runs on the smaller model; the reviewer on the larger. A session fixing alone does the
|
|
reading itself and uses one subagent only for the review.
|
|
|
|
## How it is checked
|
|
|
|
- A small fix has one pull request with one or few commits naming its issue, opened after its review: a pull
|
|
request with many heads is a fix reviewed after its push.
|
|
- Its issue moves to `resolved` within the hour its delivery plan ends.
|