docs: define post-merge queue state
This commit is contained in:
parent
486bbd10a4
commit
8e6423a07c
5 changed files with 40 additions and 4 deletions
|
|
@ -125,7 +125,12 @@ triage bug, and the move is to say so on the issue, not to guess.
|
||||||
merge — a live proof of a workflow trigger, a released-artifact check,
|
merge — a live proof of a workflow trigger, a released-artifact check,
|
||||||
anything whose subject does not exist until the change is on the base
|
anything whose subject does not exist until the change is on the base
|
||||||
branch — the same-repo PR uses `Refs #N` instead, and triage closes the
|
branch — the same-repo PR uses `Refs #N` instead, and triage closes the
|
||||||
issue by hand on the evidence, exactly as it does for cross-repo work.
|
issue by hand on the evidence, exactly as it does for cross-repo work. The
|
||||||
|
merge releases the claim: the issue moves to `post-merge`, the builder
|
||||||
|
walks away, and triage owns verification and closure. If evidence later
|
||||||
|
requires corrective build work, triage returns it to `ready` or mints a
|
||||||
|
fresh `ready` issue; any builder claims from current `main`, and the
|
||||||
|
original builder has no special standing.
|
||||||
The issue body is what says so; you never judge which issues qualify, and
|
The issue body is what says so; you never judge which issues qualify, and
|
||||||
absent that instruction `Closes #N` remains the default. The exception was
|
absent that instruction `Closes #N` remains the default. The exception was
|
||||||
bought the hard way: #143 carried `Closes #137` as doctrine then required,
|
bought the hard way: #143 carried `Closes #137` as doctrine then required,
|
||||||
|
|
|
||||||
23
LABELS.md
23
LABELS.md
|
|
@ -52,14 +52,32 @@ strips it on sight).
|
||||||
| `ready` | `#0E8A16` | triaged, spec complete, unblocked — a builder can start now and succeed | triage |
|
| `ready` | `#0E8A16` | triaged, spec complete, unblocked — a builder can start now and succeed | triage |
|
||||||
| `claimed` | `#1D76DB` | a builder owns it: assignee set, a draft PR expected shortly | the claiming builder |
|
| `claimed` | `#1D76DB` | a builder owns it: assignee set, a draft PR expected shortly | the claiming builder |
|
||||||
| `blocked` | `#6A737D` | waiting on another issue or PR (`Blocked by #N` in the body names it) | triage; anyone may correct it |
|
| `blocked` | `#6A737D` | waiting on another issue or PR (`Blocked by #N` in the body names it) | triage; anyone may correct it |
|
||||||
|
| `post-merge` | `#006B75` | the Refs-linked PR merged; post-merge acceptance criteria remain; the claim is released — nothing here is buildable and nobody owes a draft | the sweep or triage |
|
||||||
| `epic` | `#5319E7` | organizes other issues via a dependency-ordered task list; **builders never pick an epic** | triage |
|
| `epic` | `#5319E7` | organizes other issues via a dependency-ordered task list; **builders never pick an epic** | triage |
|
||||||
|
|
||||||
The work-queue sweep enforces the invariant a board scan relies on: every open issue is either
|
The work-queue sweep enforces the invariant a board scan relies on: every open issue is either
|
||||||
`needs-triage`, `epic`, or carries exactly one of `ready` / `claimed` /
|
`needs-triage`, `epic`, or carries exactly one of `ready` / `claimed` /
|
||||||
`blocked`. It flags conflicts rather than guessing intent. A `claimed` issue
|
`blocked` / `post-merge`. It flags conflicts rather than guessing intent. A `claimed` issue
|
||||||
with no open PR and no activity for 48 hours is reclaimed by the sweep: it
|
with no open PR and no activity for 48 hours is reclaimed by the sweep: it
|
||||||
comments, unassigns the stale owner, and restores `ready`.
|
comments, unassigns the stale owner, and restores `ready`.
|
||||||
|
|
||||||
|
When a merged PR references a `claimed` issue with `Refs #N` and unchecked
|
||||||
|
criteria remain, the sweep moves the issue to `post-merge`, clears the
|
||||||
|
assignee, and comments with the remaining criteria verbatim. The comment says
|
||||||
|
that the claim is released and that triage owes a follow-up naming the owner
|
||||||
|
and wake condition for completion. Triage writes that full transition comment
|
||||||
|
in the same tick when it or the operator makes the move by hand. The sweep
|
||||||
|
never reclaims `post-merge`: weeks of quiet can be the state working.
|
||||||
|
|
||||||
|
`post-merge` never composes with `blocked`; the transition comment carries the
|
||||||
|
wait. It never composes with `attention`, because releasing the claim clears
|
||||||
|
the assignee and leaves nobody parked-for. An assigned `post-merge` issue is
|
||||||
|
flagged rather than repaired: a hand-assignment is intent. `needs-ruling`
|
||||||
|
still composes. When the remainder becomes buildable, triage moves
|
||||||
|
`post-merge` to `ready` or mints a fresh `ready` issue. Any builder may claim
|
||||||
|
that work from current `main`; the original builder has no special standing,
|
||||||
|
and re-entry does not set `attention`.
|
||||||
|
|
||||||
## Cross-cutting (PRs and issues)
|
## Cross-cutting (PRs and issues)
|
||||||
|
|
||||||
| Label | Color | Meaning |
|
| Label | Color | Meaning |
|
||||||
|
|
@ -155,7 +173,8 @@ unanswered `attention` is exactly the silence the 48-hour reclaim should
|
||||||
take. It is hand-set doctrine only: nothing in `actions/` sets, clears,
|
take. It is hand-set doctrine only: nothing in `actions/` sets, clears,
|
||||||
reads, or validates it, and no reconciler enforces the assignee requirement.
|
reads, or validates it, and no reconciler enforces the assignee requirement.
|
||||||
An `attention` issue without an assignee is therefore a board bug, not a
|
An `attention` issue without an assignee is therefore a board bug, not a
|
||||||
demand; anyone may assign it or remove the flag.
|
demand; anyone may assign it or remove the flag. It never composes with
|
||||||
|
`post-merge`, whose released claim has no assignee to answer the demand.
|
||||||
|
|
||||||
The three signals are mutually distinct: `attention` means an assignee owes
|
The three signals are mutually distinct: `attention` means an assignee owes
|
||||||
a move; `needs-ruling` means a human owes a decision under
|
a move; `needs-ruling` means a human owes a decision under
|
||||||
|
|
|
||||||
12
TRIAGE.md
12
TRIAGE.md
|
|
@ -96,7 +96,12 @@ Every issue you mint carries, in this order:
|
||||||
rather than `Closes #N`. A criterion that survives the merge only if
|
rather than `Closes #N`. A criterion that survives the merge only if
|
||||||
someone remembers to reopen the issue is an incomplete criterion — #137's
|
someone remembers to reopen the issue is an incomplete criterion — #137's
|
||||||
amended body is the worked example, reopened by hand after `Closes #137`
|
amended body is the worked example, reopened by hand after `Closes #137`
|
||||||
closed it with the criterion unmet (#151).
|
closed it with the criterion unmet (#151). The merge moves the issue to
|
||||||
|
`post-merge` and releases the claim. The sweep writes the transition
|
||||||
|
comment when it derives the move; when triage or the operator moves it by
|
||||||
|
hand, triage writes the comment in the same tick. In either case triage
|
||||||
|
follows up with the remaining criteria, their owner, and the wake condition
|
||||||
|
for completion.
|
||||||
- **Test plan**: what proves it, including the cases that must fail.
|
- **Test plan**: what proves it, including the cases that must fail.
|
||||||
- **Dependencies**: `Blocked by #N` / `Blocks #N`, and `Part of #E` when an
|
- **Dependencies**: `Blocked by #N` / `Blocks #N`, and `Part of #E` when an
|
||||||
epic organizes it. Name a cross-repo dependency the same way with its
|
epic organizes it. Name a cross-repo dependency the same way with its
|
||||||
|
|
@ -126,6 +131,11 @@ itself. Keep the checklist current — a stale epic misleads every scan.
|
||||||
lands, and flags a blocked issue whose dependency declaration is unreadable.
|
lands, and flags a blocked issue whose dependency declaration is unreadable.
|
||||||
- The sweep reclaims abandoned claims after 48 hours: `claimed` + no open PR
|
- The sweep reclaims abandoned claims after 48 hours: `claimed` + no open PR
|
||||||
+ no activity → comment, unassign, restore `ready`.
|
+ no activity → comment, unassign, restore `ready`.
|
||||||
|
- `post-merge` is triage's completion queue, not a parked claim. Tick verified
|
||||||
|
criteria and close under the criterion's existing contract. If corrective
|
||||||
|
build work becomes necessary, move it to `ready` or mint a fresh `ready`
|
||||||
|
issue: any builder claims from current `main`, the original builder has no
|
||||||
|
special standing, and re-entry does not set `attention`.
|
||||||
- Automation never guesses intent. Resolve the conflict comments it leaves on
|
- Automation never guesses intent. Resolve the conflict comments it leaves on
|
||||||
malformed queue states, and close or extend completed epics when nudged.
|
malformed queue states, and close or extend completed epics when nudged.
|
||||||
- **Close obsolete issues** with the reason and a link to what obsoleted
|
- **Close obsolete issues** with the reason and a link to what obsoleted
|
||||||
|
|
|
||||||
|
|
@ -472,6 +472,7 @@ release|0E8A16|Release flow and version/packaging work
|
||||||
needs-triage|FBCA04|Did not come through triage — owes normalization or conversion to a discussion
|
needs-triage|FBCA04|Did not come through triage — owes normalization or conversion to a discussion
|
||||||
ready|0E8A16|Triaged, spec complete, unblocked — a builder can start now and succeed
|
ready|0E8A16|Triaged, spec complete, unblocked — a builder can start now and succeed
|
||||||
claimed|1D76DB|A builder owns it: assignee set, draft PR expected shortly
|
claimed|1D76DB|A builder owns it: assignee set, draft PR expected shortly
|
||||||
|
post-merge|006B75|Refs-linked PR merged; post-merge criteria remain and triage owns completion
|
||||||
epic|5319E7|Organizes other issues via a dependency-ordered task list — builders never pick it
|
epic|5319E7|Organizes other issues via a dependency-ordered task list — builders never pick it
|
||||||
EOF
|
EOF
|
||||||
}
|
}
|
||||||
|
|
|
||||||
1
changelog.d/175.md
Normal file
1
changelog.d/175.md
Normal file
|
|
@ -0,0 +1 @@
|
||||||
|
- Add `post-merge` issue state for merged `Refs` work awaiting triage-owned verification.
|
||||||
Loading…
Reference in a new issue