Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions changelog.d/fixed-merge-train-ci-review-overlap-hint.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
- The Activity Monitor no longer draws a merge train over PRs that are still at CI / Review: the merge train is a merge-queue concept, so only PRs at 080 and beyond ride one and the header counts only them. A PR short of the queue whose files overlap another open PR's now shows a muted "overlaps #N" badge ("overlaps #15637 (sidebar.html, index.html) β€” will queue behind it") instead of a rail, ordinal or "1st:" header ([#15653](https://github.com/hivecommons/hive/issues/15653)).

The train header no longer says "not in this view: 7 more" over PRs that were never in the merge queue: `size`/`members` count only the PRs riding in this payload, and when the page does not draw every member the header says why β€” `on another page: #N`, `hidden by the filter: #N`, `not in this payload: #N`. The header's hover explains the mechanics (members touch the same files, merge one at a time in order, each rebased onto the base only after the PR ahead merges) and a member's hover says its slot, `Position: 3rd of 4 Β· after #X merges`.
2 changes: 1 addition & 1 deletion src/docs/api-reference/dashboard-misc.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `GET` | `/api/budget-ignore` | Dashboard auth/session | Budget Ignore Get | `pkg/dashboard/api.go:172` |
| `POST` | `/api/budget-ignore` | Owner only | Budget Ignore Set | `pkg/dashboard/api.go:173` |
| `GET` | `/api/summaries` | Dashboard auth/session | Summaries | `pkg/dashboard/api.go:185` |
| `GET` | `/api/stage-tracker` | Dashboard auth/session | Stage Tracker: every open issue and pull request of the watched repos for the Hive activity monitor β€” actionable, held, claimed, in-progress, covered-by-PR, filtered (`needs-*`), draft and exempt-labelled items alike, each with `stage`, `stage_since`, `labels`, `created_at`, `author_kind`, `modifiers`, `claimant: {kind: hive-agent|clanker|person, login, agent, hive, since, source: claim-ledger|claim-comment|assignee|kick-history|author}` naming who holds a claimed / in-progress issue or a PR under review or rework (absent when nobody is named; mirrored onto `linked_prs[]`), (PRs) `sentinel_alert` / `sentinel_findings` / `sentinel_reason` when the sentinel flagged the PR, `decision_needed` on a row parked on a person (085 / 045 / 015, the needs-human pill; mirrored onto the issue's `linked_prs[]` entry): `{question, asked_by, since, blocker, blocker_reason, options: [{action, label, enabled, reason_if_disabled}]}` β€” the reviewer's own decision question when the verdict record has one, the blocker in plain words, and the applicable actions under the row context menu's action ids (`decide:delegate` first), (PRs) `lineage` on the hive's copy of an adopted PR β€” `{kind: adopted|superseded|rebased-by-hive, from_number, from_url, from_author, from_author_kind, to_number, to_url, at, reason}`, derived from the stage store's adoption record or the `hive/adopt-<n>` head branch, mirrored onto the issue's `linked_prs[]` entry; absent on every other row β€” and (issues) `linked_prs`; items with no stage yet report stage `0` "Open"; `needs_human_labels` is the "a person must act" label set behind the monitor's Needs human facet (the same list as `/api/status.labelPresets[needs-human]`); `recently_merged` lists the PRs (`repo`, `number`, `merged_at`) whose `pr_merged` audit entry is under 30 minutes old, so a client diffing two payloads can tell a merge from a close; a PR in a conflict-aware merge train carries `merge_train` `{id, state, front, position, size, attempt, max_attempts, overlap_files, ahead, length, head_number, head_state, head_reason, head_since, eta_s, eta_at, eta_basis, late, stalled, stalled_s}` β€” `head_state` one of `needs-human` / `ci` / `soaking` / `ready` / `merging` / `fixing` / `unknown` with `head_reason` in plain words; `eta_s` / `eta_at` the estimated wait for this member's own merge attempt (own remaining soak + each PR ahead's remaining soak or one sweep + the next sweep tick; absent while the head waits on a person or CI), `eta_at` anchored to the member's first estimate at its position so a countdown survives polls, `eta_basis` its short reading ("2 ahead Β· head soaking 12m Β· next sweep in 40s"), `late` once now has overrun the first estimate twice over, `stalled` / `stalled_s` once the head has sat longer than `governor.merge_train_stall_warn_s` ([#15395](https://github.com/hivecommons/hive/issues/15395)); a PR the queue holds because another open PR declares the same `Fixes #N` carries no `merge_train` and a `merge_gate` of `{state: "duplicate-of:<winner>", duplicate_of, duplicate_issue}` plus the `needs-decision` modifier (the queue keeps one PR per issue: green first, then the earlier-opened); a PR GitHub reports conflicting on its own, or one under repair (stage/070, 071, 072, 074, 085, or a red required check), carries no `merge_train` and is not counted in any member's `size` / `length` β€” a repaired member the view dropped carries `left_train: {why: fixing|needs-author|returned-to-contributor|adopted-by-hive|needs-decision|checks-failing, note}` instead (mirrored onto the issue's `linked_prs[]` entry), and a train left with one member reports no `merge_train` at all β€” the state slugs (`front`, `queued-behind`) are payload values only, the SPA renders ordinal places ("Merge queued Β· 1st of 2", with the train's tag when more than one train is on the page). Served from a server-side cache rebuilt at most every `dashboard.stage_tracker.cache_ttl_s` (default `governor.eval_interval_s`) from the spoke's existing snapshot β€” a request never calls GitHub. Carries `generated_at`, `source` (`cache` or `fresh`), `cache_ttl_s`, an `ETag` and `Cache-Control: private, max-age=<remaining>`; `If-None-Match` yields 304. Each hit is recorded under REST caller `dashboard:stage-tracker` so `/api/gh-rate-limits` shows it charged nothing. | `pkg/dashboard/api.go:186` |
| `GET` | `/api/stage-tracker` | Dashboard auth/session | Stage Tracker: every open issue and pull request of the watched repos for the Hive activity monitor β€” actionable, held, claimed, in-progress, covered-by-PR, filtered (`needs-*`), draft and exempt-labelled items alike, each with `stage`, `stage_since`, `labels`, `created_at`, `author_kind`, `modifiers`, `claimant: {kind: hive-agent|clanker|person, login, agent, hive, since, source: claim-ledger|claim-comment|assignee|kick-history|author}` naming who holds a claimed / in-progress issue or a PR under review or rework (absent when nobody is named; mirrored onto `linked_prs[]`), (PRs) `sentinel_alert` / `sentinel_findings` / `sentinel_reason` when the sentinel flagged the PR, `decision_needed` on a row parked on a person (085 / 045 / 015, the needs-human pill; mirrored onto the issue's `linked_prs[]` entry): `{question, asked_by, since, blocker, blocker_reason, options: [{action, label, enabled, reason_if_disabled}]}` β€” the reviewer's own decision question when the verdict record has one, the blocker in plain words, and the applicable actions under the row context menu's action ids (`decide:delegate` first), (PRs) `lineage` on the hive's copy of an adopted PR β€” `{kind: adopted|superseded|rebased-by-hive, from_number, from_url, from_author, from_author_kind, to_number, to_url, at, reason}`, derived from the stage store's adoption record or the `hive/adopt-<n>` head branch, mirrored onto the issue's `linked_prs[]` entry; absent on every other row β€” and (issues) `linked_prs`; items with no stage yet report stage `0` "Open"; `needs_human_labels` is the "a person must act" label set behind the monitor's Needs human facet (the same list as `/api/status.labelPresets[needs-human]`); `recently_merged` lists the PRs (`repo`, `number`, `merged_at`) whose `pr_merged` audit entry is under 30 minutes old, so a client diffing two payloads can tell a merge from a close; a PR in a conflict-aware merge train carries `merge_train` `{id, state, front, position, size, attempt, max_attempts, overlap_files, ahead, length, head_number, head_state, head_reason, head_since, eta_s, eta_at, eta_basis, late, stalled, stalled_s}` β€” `head_state` one of `needs-human` / `ci` / `soaking` / `ready` / `merging` / `fixing` / `unknown` with `head_reason` in plain words; `eta_s` / `eta_at` the estimated wait for this member's own merge attempt (own remaining soak + each PR ahead's remaining soak or one sweep + the next sweep tick; absent while the head waits on a person or CI), `eta_at` anchored to the member's first estimate at its position so a countdown survives polls, `eta_basis` its short reading ("2 ahead Β· head soaking 12m Β· next sweep in 40s"), `late` once now has overrun the first estimate twice over, `stalled` / `stalled_s` once the head has sat longer than `governor.merge_train_stall_warn_s` ([#15395](https://github.com/hivecommons/hive/issues/15395)); a PR the queue holds because another open PR declares the same `Fixes #N` carries no `merge_train` and a `merge_gate` of `{state: "duplicate-of:<winner>", duplicate_of, duplicate_issue}` plus the `needs-decision` modifier (the queue keeps one PR per issue: green first, then the earlier-opened); a PR GitHub reports conflicting on its own, or one under repair (stage/070, 071, 072, 074, 085, or a red required check), carries no `merge_train` and is not counted in any member's `size` / `length` β€” a repaired member the view dropped carries `left_train: {why: fixing|needs-author|returned-to-contributor|adopted-by-hive|needs-decision|checks-failing, note}` instead (mirrored onto the issue's `linked_prs[]` entry), and a train left with one member reports no `merge_train` at all; a PR short of the merge queue (below stage/080) the planner ordered rides no train either β€” it carries `overlap: {behind, with, files, note}` ("overlaps #15637 (sidebar.html, index.html) β€” will queue behind it") and no `merge_train`, and counts in no member's `size` β€” the state slugs (`front`, `queued-behind`) are payload values only, the SPA renders ordinal places ("Merge queued Β· 1st of 2", with the train's tag when more than one train is on the page). Served from a server-side cache rebuilt at most every `dashboard.stage_tracker.cache_ttl_s` (default `governor.eval_interval_s`) from the spoke's existing snapshot β€” a request never calls GitHub. Carries `generated_at`, `source` (`cache` or `fresh`), `cache_ttl_s`, an `ETag` and `Cache-Control: private, max-age=<remaining>`; `If-None-Match` yields 304. Each hit is recorded under REST caller `dashboard:stage-tracker` so `/api/gh-rate-limits` shows it charged nothing. | `pkg/dashboard/api.go:186` |
| `POST` | `/api/prs/{owner}/{repo}/{number}/queue-automerge` | Merger/owner role | Queue PRAuto Merge | `pkg/dashboard/api.go:187` |
| `GET` | `/api/inference/models/{backend}` | Dashboard auth/session | Inference Models | `pkg/dashboard/api.go:363` |
| `GET` | `/api/hive-id` | Dashboard auth/session | Hive IDGet | `pkg/dashboard/api.go:425` |
Expand Down
4 changes: 3 additions & 1 deletion src/docs/dashboard-sections.md
Original file line number Diff line number Diff line change
Expand Up @@ -933,12 +933,14 @@ When several approved PRs to the same base touch the same files, the automerge l

The tooltip lists the PRs ahead and the overlapping files. Waiting siblings are never red, never `needs human`; a `needs-rebase` label on one is reported under `stale_labels`, the train repairs it. Each item carries `merge_gate.state` (`queued-behind` / `rebasing` / `rebase-exhausted` / `front`, with an honest `reason` such as `behind #15074 in merge train (3rd of 4, overlapping files: stage_tracker.go, index.html)`) and `merge_train{id, state, front, position, size, attempt, max_attempts, overlap_files, ahead, members}`; the id is `<base>#<front>` and `members` is the whole roster in merge order.

**The header counts the rows under it.** A member drawn as a sub-row of its linked issue (`nested_under`) still sits in the train run β€” the issue row rides its open PR's train, in that PR's merge order, and wears the rail β€” so a train of three is three rows under one header whether or not its PRs have issues. When a filter or tab hides some members, the header says so and names them: `merge train Β· 1 of 3 PRs here Β· 1st: #15425 Β· not in this view: #15529, #15530`; it never claims `3 PRs` over one row (hive's v5#15425 did, with #15529 and #15530 drawn under their issues). No member on the page, no header.
**The header counts the rows under it.** A member drawn as a sub-row of its linked issue (`nested_under`) still sits in the train run β€” the issue row rides its open PR's train, in that PR's merge order, and wears the rail β€” so a train of three is three rows under one header whether or not its PRs have issues. When the page does not carry every member, the header says where the rest are and names them β€” `merge train Β· 1 of 3 PRs here Β· 1st: #15425 Β· on another page: #15529 Β· hidden by the filter: #15530` (`not in this payload: #N` for one the server no longer lists) β€” never a bare "not in this view" (owner: *what does 'not in this view' mean?*) and never `3 PRs` over one row (hive's v5#15425 did, with #15529 and #15530 drawn under their issues). `size` / `members` count only the PRs in the merge queue in this payload, never the planner's wider grouping (hive's own header once read `2 of 9 PRs here Β· not in this view: 7 more` where the seven were PRs still at CI / Review). The header's hover says the mechanics: the members touch the same files, so they merge one at a time in order, and each is rebased onto the base only after the PR ahead merges; a member's own hover adds its slot, *Position: 3rd of 4 Β· after #15085 merges*. No member on the page, no header.

**Who rides.** A PR the lane leaves to a person is not a train member and never its head: an author below the lane's trust (`untrusted-author-role`, `contributor-lane:no-linked-issue`, …), the title/label human-merge rule, a human-merge path, a merge GitHub refused for review, and every other `human_merge_reason` code except the catch-all `policy`. The lane's verdict is remembered per lane and head (`noteMergeTrainOutcome`); a new head starts clean. A head the lane last saw unable to merge on its own (red required check, terminal hold, permanent refusal) stays a member but never fronts.

**PRs under repair leave the train.** A PR somebody is fixing is not a train member either: the planner (`mergeTrainUnderRepair`) skips a PR at 070 fixing, 071 needs-author, 072 returned-to-contributor or 085 needs-decision (label or stage store), and the tracker (`stageTrackerTrainUnderRepair`) drops one whose stage says so (074 adopted-by-hive included) or whose `reason` is a red required check (`required-check-failing:` / `check-failing:` / `ci-red`) β€” hive's own #15405 once led a header as `merge train Β· 2 PRs Β· 1st: #15405` while its own chevron read *Fixing* (a maintainer had just requested changes). The dropped row carries `left_train: {why, note}` and no `merge_train`: no ordinal, no rail, and its hover ends with the one muted line *Merge train: left the merge train while being fixed; rejoins when green*. The survivors close ranks β€” `size`, `position`, `front`, `ahead`, `members` are recomputed, and the next in line fronts when the front itself left β€” and a train left with one member is no train: no header, no ordinal, the 080 row back to *Green and approved; waiting for the automerge lane to admit it*. The exception is the `rebase-exhausted` tail at 085: the train put it there, and it stays so the person who rebases it sees where it merges. Provisional members (050 / 060 with nothing red, [#15580](https://github.com/hivecommons/hive/issues/15580)) keep their slot.

**The train starts at 080.** The merge train is a merge-queue concept: only PRs at 080 and beyond β€” green, approved, soaking or merging β€” ride one, and the header counts only them. A PR the planner has ordered while it is still at CI / Review (050 / 060) rides no train (`stageTrackerBelowMergeQueue`): hive's own page once led `merge train Β· 2 PRs Β· 1st: #15637 β€” overlapping: sidebar.html, index.html` over #15637 and #15633 while both chevrons read *CI / Review*. Such a row carries `overlap: {behind, with, files, note}` instead of `merge_train` β€” no rail, no ordinal, no header β€” and shows one muted badge **overlaps #15637** whose hover is the note, *Not in the merge queue yet: overlaps #15637 (sidebar.html, index.html) β€” will queue behind it* (the planner's own front reads *overlaps #15633 (…) β€” merges ahead of it once both are ready*). The members that do ride close ranks around it, and a train left with one 080 member is no train.

**Queue position, countdown, stall** ([#15395](https://github.com/hivecommons/hive/issues/15395)). The queued chip is its place in the queue and nothing else β€” **Merge queued Β· 2nd of 6 Β· ~4m** β€” so it reads the same whether or not a merge sweep is evaluating it: the sweep is the spinning ⬑ glyph and a *Checking now…* line in the hover, never a change of words (one label per chevron), and no state slug (`queued-behind`, `front`) ever reaches the page. The hover is the place sentence β€” *2nd of 6 in the merge queue Β· behind #15253 (soaking, 12m left) Β· ETA ~25m (2 ahead Β· head soaking 12m Β· next pass in 40s). Hive merges one at a time, in order.*; the head's reads *1st of 6 in the merge queue Β· merges next Β· ETA ~13m.* β€” or, when the head is on a person or on CI, the blocker instead of a clock: *… behind #15253 (waiting for a maintainer (untrusted author)) Β· no estimate until #15253 moves.* Every train state β€” the 1st included β€” lights the **Merge queue** column, whatever numeric stage the lane holds the head at (the train's facts are mirrored onto a head still at 050/060; hive's own #15400 once lit CI / Review beside its 2nd-place sibling) β€” a head under repair is no member (below) and lights CI / Review. The server adds to each member's `merge_train`: `length`, `head_number`, `head_state` (`needs-human` / `ci` / `soaking` / `ready` / `merging` / `fixing` / `unknown`), `head_reason` (plain words), `head_since`, `eta_s`, `eta_at`, `eta_basis`, `late`, `stalled`, `stalled_s`.

**One PR per issue** ([#15395](https://github.com/hivecommons/hive/issues/15395)). Two open PRs declaring the same `Fixes #N` never both ride the queue (hive's own #15402 and #15407, both for #15396, once sat side by side as "waiting its turn"). Before the trains are grouped the sweep keeps one PR per closing issue β€” a green head (not conflicting, not blocked on a red required check) beats a red one; among equals the earlier-opened wins β€” and holds the other out of every train with the stage reason `merge-train:duplicate-of#<winner>:<issue>/0:0/0:`. The held row's gate reads `duplicate-of:<winner>` (`merge_gate.duplicate_of`, `merge_gate.duplicate_issue`), its chip **Duplicate of #15402 Β· needs a pick** with no clock, it carries no `merge_train`, and it wears `needs-decision` so both PRs sit under their issue with the hold visible. *Let hive decide* on either row takes the existing supersede path (rule `one-pr-per-issue`): on the held PR it closes it as superseded by the kept one with a credit comment, through the same write gate as every delegate close; on the kept PR it releases it and names the duplicate the queue holds (or, if the kept PR has since gone red, only recommends the fix β€” the queue re-picks on its next pass, so an earlier red PR yields to a later green one).
Expand Down
Loading
Loading