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
1 change: 1 addition & 0 deletions changelog.d/changed-human-merge-reason.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Hive activity monitor: every `090 Ready for human merge` row and its tooltip now say why a person must merge (`· workflow files`, `· untrusted author`, `· branch protection`, `· auto-merge off`, `· unauthorized`, … falling back to `· policy`), derived from the stage record's lane reason; nested PR sub-rows and the needs-attention headline carry the same (#14658)
2 changes: 1 addition & 1 deletion src/docs/dashboard-sections.md

Large diffs are not rendered by default.

11 changes: 10 additions & 1 deletion src/docs/hive-merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -609,7 +609,16 @@ carrying the text ([#13041](https://github.com/hivecommons/hive/issues/13041)),
hold / sentinel alert → `stage/085-needs-decision`, untrusted author with an approve verdict at the
current head, green checks, DCO and soak done →
`stage/090-ready-for-human-merge` (only a maintainer's `/lgtm` `/approve` is
missing), merged → no stage), plus one `role/*` label saying
missing; the dashboard derives a compact **human-merge reason code** from the
090 record's lane reason — `prstage.HumanMergeReason` — so the gate cell says
why a person merges: `workflow-files` (`contributor-lane:workflow-path`),
`tests-removed`, `manual-merge-policy` (`human-merge-path`), `branch-protection`,
`merge-method`, `auto-merge-off` (`repo-auto-merge-disabled`), `untrusted-author`
(every trust reason: `untrusted-author-role`, `claim-tier-untrusted`, `no-claim`,
`no-linked-issue`, `claim-unverified`, `claim-author-mismatch`, `claim-other-hive`,
`author-association`), `unauthorized` (the App's 403, #14595), `reviewer-deferred`
(`reviewer-verdict:requires_human` a trusted merger approved), and `policy` for
any other lane reason, quoted in the tooltip; #14658), merged → no stage), plus one `role/*` label saying
which admission tier the lane actually used, one `author/*` label saying who
wrote the PR (`human`, `clanker` = a contributor's hive, `hive` = this repo's
own; #12581) and `stage/stalled` when nobody
Expand Down
53 changes: 52 additions & 1 deletion src/pkg/dashboard/stage_tracker.go
Original file line number Diff line number Diff line change
Expand Up @@ -301,6 +301,15 @@ type StageTrackerItem struct {
// the maintainer's merge click.
HumanApprover string `json:"human_approver,omitempty"`
ManualMerge bool `json:"manual_merge,omitempty"`
// HumanMergeReason is, at 090, the compact code naming why a person
// and not the hive merges this PR (prstage.HumanMergeReason*:
// "workflow-files", "untrusted-author", "branch-protection", …;
// "policy" when the lane reason has no more specific code), and
// HumanMergeReasonText the one-sentence tooltip for it, so the gate
// cell reads "Ready for human merge · workflow files" rather than
// leaving the owner to ask why (hivecommons/hive#14658).
HumanMergeReason string `json:"human_merge_reason,omitempty"`
HumanMergeReasonText string `json:"human_merge_reason_text,omitempty"`
// UnauthorizedStep is set when the item wears hive:unauthorized: the
// step the hive's GitHub App is not permitted to take, in words
// ("approve workflow runs"), from the `unauthorized:<step>` stage
Expand Down Expand Up @@ -376,7 +385,14 @@ type StageTrackerLinkedPR struct {
// so a sub-row under an issue names the alert too.
SentinelAlert bool `json:"sentinel_alert,omitempty"`
SentinelReason string `json:"sentinel_reason,omitempty"`
Head string `json:"head,omitempty"`
// HumanApprover / ManualMerge / HumanMergeReason(Text) mirror the
// nested PR's 090 fields so a sub-row's gate cell says why a person
// merges it, as the top-level row would (hivecommons/hive#14658).
HumanApprover string `json:"human_approver,omitempty"`
ManualMerge bool `json:"manual_merge,omitempty"`
HumanMergeReason string `json:"human_merge_reason,omitempty"`
HumanMergeReasonText string `json:"human_merge_reason_text,omitempty"`
Head string `json:"head,omitempty"`
}

// Stage numbers the tracker lays out by. Pinned to stagelabels.Table in
Expand Down Expand Up @@ -856,6 +872,36 @@ func stageTrackerManualMergeReason(reason string) bool {
return false
}

// Gate-cell words and tooltips per prstage.HumanMergeReason* code: why a
// person, not the hive, merges a PR parked at 090 (hivecommons/hive#14658).
var stageTrackerHumanMergeReasonWords = map[string][2]string{
stageengineprstage.HumanMergeReasonWorkflowFiles: {"workflow files", "Changes .github/workflows/** (or action files) — the hive never merges workflow changes and its GitHub App lacks the workflows permission; click Merge on GitHub"},
stageengineprstage.HumanMergeReasonTestsRemoved: {"tests removed", "Deletes tests — the hive never merges a PR that removes tests unattended; a maintainer reviews the deletion and clicks Merge"},
stageengineprstage.HumanMergeReasonManualMergePolicy: {"manual-merge policy", "Touches a path listed in auto_merge.human_merge_paths — the hive never merges it unattended; click Merge on GitHub"},
stageengineprstage.HumanMergeReasonBranchProtection: {"branch protection", "Branch protection or a ruleset requires an approving review the hive's GitHub App cannot give; approve on GitHub (or let the App bypass) and the hive merges, or click Merge"},
stageengineprstage.HumanMergeReasonMergeMethod: {"merge method", "The repository disallows the merge method this PR needs (a forward merge or merge-commit PR is never squashed); merge by hand with an allowed method or allow it in the repository settings"},
stageengineprstage.HumanMergeReasonAutoMergeOff: {"auto-merge off", "Auto-merge is switched off for this repository or lane, so every merge is a person's; click Merge on GitHub"},
stageengineprstage.HumanMergeReasonUntrustedAuthor: {"untrusted author", "No lane can vouch for the author (trust tier below require_tiers, no verified claim, or no trusted role), so the hive does not merge; a maintainer's /lgtm + /approve (or Merge) lands it"},
stageengineprstage.HumanMergeReasonUnauthorized: {"unauthorized", "The hive's GitHub App is not permitted to take the merge step (GitHub answered 403); a maintainer merges by hand — see the hive:unauthorized note on the PR"},
stageengineprstage.HumanMergeReasonReviewerDeferred: {"reviewer deferred", "The reviewer swarm returned requires_human on this head and a trusted merger approved it; the hive leaves the merge itself to a person"},
}

// stageTrackerHumanMergeReason derives, from a 090 stage reason, the
// compact code, the gate-cell word and the tooltip saying why a person
// must merge. An unrecognised lane reason falls back to the "policy" code
// with the raw reason in the tooltip; an empty reason yields "".
func stageTrackerHumanMergeReason(reason string) (code, word, tip string) {
code = stageengineprstage.HumanMergeReason(reason)
if code == "" {
return "", "", ""
}
if w, ok := stageTrackerHumanMergeReasonWords[code]; ok {
return code, w[0], w[1]
}
base, _ := stagelabels.HumanApprovedReason(reason)
return stageengineprstage.HumanMergeReasonPolicy, "policy", "The merge lane will not merge this unattended (lane reason `" + strings.TrimSpace(base) + "`); a maintainer merges by hand"
}

// trackerSoakRemainingRE pulls the time left out of the lane's
// `contributor-lane:soaking(remaining=12m0s)` reason.
var trackerSoakRemainingRE = regexp.MustCompile(`remaining=([0-9hms.]+)`)
Expand Down Expand Up @@ -1188,6 +1234,9 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto
base, approver := stagelabels.HumanApprovedReason(it.Reason)
it.HumanApprover = approver
it.ManualMerge = stageTrackerManualMergeReason(base)
if stage == stagelabels.ReadyForHumanMerge {
it.HumanMergeReason, _, it.HumanMergeReasonText = stageTrackerHumanMergeReason(it.Reason)
}
if slices.Contains(it.Modifiers, modUnauthorized) {
it.UnauthorizedStep, it.Unauthorized = stageTrackerUnauthorized(it.Reason)
}
Expand Down Expand Up @@ -1690,6 +1739,8 @@ func stageTrackerResolveLinkedPRs(items []StageTrackerItem) {
lp.Title, lp.Author, lp.AuthorKind, lp.Stage = pr.Title, pr.Author, pr.AuthorKind, pr.Stage
lp.StageSince, lp.Caption = pr.StageSince, pr.Caption
lp.SentinelAlert, lp.SentinelReason, lp.Head = pr.SentinelAlert, pr.SentinelReason, pr.Head
lp.HumanApprover, lp.ManualMerge = pr.HumanApprover, pr.ManualMerge
lp.HumanMergeReason, lp.HumanMergeReasonText = pr.HumanMergeReason, pr.HumanMergeReasonText
lp.BaseRef = pr.BaseRef
if len(pr.Modifiers) > 0 {
lp.Modifiers = append([]string(nil), pr.Modifiers...)
Expand Down
20 changes: 20 additions & 0 deletions src/pkg/dashboard/stage_tracker_sentinel_lane_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,10 @@ func stageTrackerManualMergeJS(t *testing.T, html string) string {
return strings.Join([]string{
jsConstLine(t, html, "STAGE_TRACKER_READY_FOR_HUMAN_MERGE"),
jsConstLine(t, html, "STAGE_TRACKER_MANUAL_MERGE_WORD"),
jsConstLine(t, html, "STAGE_TRACKER_HUMAN_MERGE_REASON_WORD"),
jsFunc(t, html, "stageTrackerHumanMergeReasonWord"),
jsFunc(t, html, "stageTrackerManualMergeWord"),
jsFunc(t, html, "stageTrackerReadyForHumanWord"),
jsConstLine(t, html, "STAGE_TRACKER_HUMAN_GATED"),
jsConstLine(t, html, "STAGE_TRACKER_UNAUTHORIZED_WORD"),
jsFunc(t, html, "stageTrackerUnauthorizedWord"),
Expand Down Expand Up @@ -383,6 +386,23 @@ assert.ok(!manual.includes('entinel') && !manual.includes('Needs human decision'
const plain090 = stageTrackerRowHtml(P('o/r', 402, 90, { reason: 'untrusted-author-role' }), stages, ctx);
assert.ok(!plain090.includes('Awaiting human merge') && plain090.includes('<span class="ham-detour">Ready for human merge</span>'), 'a trust-blocked 090 keeps the stage word: ' + plain090);

// Every 090 word says WHY a person merges (hivecommons/hive#14658): the
// payload's human_merge_reason code becomes the word's tail, its
// human_merge_reason_text leads the lit chevron's tooltip, and a nested
// linked PR carries the same.
assert.strictEqual(stageTrackerHumanMergeReasonWord({ human_merge_reason: 'workflow-files' }), 'workflow files');
assert.strictEqual(stageTrackerHumanMergeReasonWord({ human_merge_reason: 'some-new-code' }), 'some new code');
assert.strictEqual(stageTrackerHumanMergeReasonWord({}), '');
assert.strictEqual(stageTrackerManualMergeWord({ human_approver: 'clubanderson', human_merge_reason: 'workflow-files' }), 'Awaiting human merge · workflow files · approved by @clubanderson');
const whyTip = 'Changes .github/workflows/** — the hive never merges workflow changes; click Merge on GitHub';
const why = stageTrackerRowHtml(P('o/r', 401, 90, { manual_merge: true, human_approver: 'clubanderson', human_merge_reason: 'workflow-files', human_merge_reason_text: whyTip }), stages, ctx);
assert.ok(why.includes('<span class="ham-detour">Awaiting human merge · workflow files · approved by @clubanderson</span>'), 'manual-merge 090 word carries the reason: ' + why);
assert.ok(why.includes('title="Awaiting human merge · workflow files · approved by @clubanderson — ' + whyTip), 'the lit 090 chevron tooltip leads with the reason: ' + why);
const whyPlain = stageTrackerRowHtml(P('o/r', 402, 90, { human_merge_reason: 'untrusted-author', human_merge_reason_text: 'No lane can vouch for the author' }), stages, ctx);
assert.ok(whyPlain.includes('<span class="ham-detour">Ready for human merge · untrusted author</span>') && whyPlain.includes('title="Ready for human merge · untrusted author — No lane can vouch for the author'), 'plain 090 word carries the reason: ' + whyPlain);
const whyNested = stageTrackerRowHtml(I('o/r', 400, 90, { linked_prs: [{ number: 401, stage: 90, title: 'Shard', manual_merge: true, human_approver: 'clubanderson', human_merge_reason: 'workflow-files', human_merge_reason_text: whyTip }] }), stages, ctx);
assert.ok(whyNested.includes('Awaiting human merge · workflow files · approved by @clubanderson'), 'nested 090 PR carries the reason: ' + whyNested);

// Decide… preface: one line per flagged PR, nothing for clean ones.
assert.strictEqual(stageTrackerSentinelPreface([P('o/r', 109, 85, flagged), P('o/r', 104, 85)]), '⚠ o/r#109 — ' + TIP);
assert.strictEqual(stageTrackerSentinelPreface([P('o/r', 104, 85)]), '');
Expand Down
79 changes: 76 additions & 3 deletions src/pkg/dashboard/stage_tracker_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -189,14 +189,87 @@ func TestStageTrackerManualMergeApproved(t *testing.T) {
if err != nil {
t.Fatal(err)
}
if !strings.Contains(string(raw), `"human_approver":"clubanderson","manual_merge":true`) {
t.Fatalf("payload lacks the manual-merge fields: %s", raw)
if !strings.Contains(string(raw), `"human_approver":"clubanderson","manual_merge":true,"human_merge_reason":"workflow-files","human_merge_reason_text":"Changes .github/workflows/**`) {
t.Fatalf("payload lacks the manual-merge / human-merge-reason fields: %s", raw)
}
if clean := trackerItem(t, resp, "pr", 101); clean.HumanApprover != "" || clean.ManualMerge {
if clean := trackerItem(t, resp, "pr", 101); clean.HumanApprover != "" || clean.ManualMerge || clean.HumanMergeReason != "" || clean.HumanMergeReasonText != "" {
t.Fatalf("PR 101 must not carry manual-merge fields: %+v", clean)
}
}

// TestStageTrackerHumanMergeReason: every 090 row names WHY a person and
// not the hive merges it (hivecommons/hive#14658) — a compact code from the
// lane reason already on the stage record plus a one-sentence tooltip; an
// unrecognised lane reason falls back to "policy" quoting it; a PR nested
// under its issue mirrors the fields onto the linked_prs entry; rows off
// 090 carry nothing.
func TestStageTrackerHumanMergeReason(t *testing.T) {
tests := []struct {
reason, wantCode, wantWord, wantTipPrefix string
}{
{"contributor-lane:workflow-path:human-approved@clubanderson", "workflow-files", "workflow files", "Changes .github/workflows/**"},
{"contributor-lane:tests-removed", "tests-removed", "tests removed", "Deletes tests"},
{"human-merge-path:human-approved@octocat", "manual-merge-policy", "manual-merge policy", "Touches a path listed in auto_merge.human_merge_paths"},
{"untrusted-author-role", "untrusted-author", "untrusted author", "No lane can vouch for the author"},
{"contributor-lane:claim-tier-untrusted", "untrusted-author", "untrusted author", "No lane can vouch"},
{"repo-auto-merge-disabled", "auto-merge-off", "auto-merge off", "Auto-merge is switched off"},
{"reviewer-verdict:requires_human:human-approved@octocat", "reviewer-deferred", "reviewer deferred", "The reviewer swarm returned requires_human"},
{"something-brand-new", "policy", "policy", "The merge lane will not merge this unattended (lane reason `something-brand-new`)"},
{"", "", "", ""},
}
for _, tt := range tests {
code, word, tip := stageTrackerHumanMergeReason(tt.reason)
if code != tt.wantCode || word != tt.wantWord || !strings.HasPrefix(tip, tt.wantTipPrefix) || (tt.wantTipPrefix == "" && tip != "") {
t.Fatalf("%q → code %q word %q tip %q; want %q %q prefix %q", tt.reason, code, word, tip, tt.wantCode, tt.wantWord, tt.wantTipPrefix)
}
}

// Through the payload: a 090 PR whose body says `Fixes #400` nests under
// the open issue and the sub-row carries the same reason, approver and
// manual_merge; the issue line mirrors the PR's stage.
now := time.Date(2026, 10, 27, 18, 0, 0, 0, time.UTC)
s, store := stageTrackerFixture(t, now)
store.Observe(stagelabels.Key("acme/console", 401), stagelabels.ReadyForHumanMerge, "contributor-lane:workflow-path:human-approved@clubanderson")
store.Observe(stagelabels.Key("acme/console", 402), stagelabels.ReadyForHumanMerge, "no-such-lane-reason")
s.statusMu.Lock()
s.status.Repos[0].ActionableIssues = append(s.status.Repos[0].ActionableIssues,
github.Issue{Number: 400, Title: "Shard the nightly mutation run", Author: "pat", AuthorIsHuman: true, Labels: []string{"stage/090-ready-for-human-merge"}})
s.status.Repos[0].OpenPrs = append(s.status.Repos[0].OpenPrs,
FrontendPR{PullRequest: github.PullRequest{Number: 401, Title: "ci(mutation): shard nightly Stryker", Author: "pat", Labels: []string{"stage/090-ready-for-human-merge", "lgtm"},
LinkedIssues: []github.PRLinkedIssue{{Number: 400}}}},
FrontendPR{PullRequest: github.PullRequest{Number: 402, Title: "Odd lane", Author: "pat", Labels: []string{"stage/090-ready-for-human-merge"}}})
s.statusMu.Unlock()
resp := s.buildStageTracker(s.status, store, now)

pr401 := trackerItem(t, resp, "pr", 401)
if pr401.HumanMergeReason != "workflow-files" || !strings.HasPrefix(pr401.HumanMergeReasonText, "Changes .github/workflows/**") || pr401.NestedUnder != 400 {
t.Fatalf("PR 401 = reason %q text %q nested %d", pr401.HumanMergeReason, pr401.HumanMergeReasonText, pr401.NestedUnder)
}
issue400 := trackerItem(t, resp, "issue", 400)
if len(issue400.LinkedPRs) != 1 {
t.Fatalf("issue 400 linked_prs = %+v", issue400.LinkedPRs)
}
lp := issue400.LinkedPRs[0]
if lp.Number != 401 || lp.Stage != 90 || !lp.ManualMerge || lp.HumanApprover != "clubanderson" || lp.HumanMergeReason != "workflow-files" || lp.HumanMergeReasonText != pr401.HumanMergeReasonText {
t.Fatalf("issue 400 nested PR lacks the human-merge fields: %+v", lp)
}
raw, err := json.Marshal(lp)
if err != nil {
t.Fatal(err)
}
if !strings.Contains(string(raw), `"human_approver":"clubanderson","manual_merge":true,"human_merge_reason":"workflow-files"`) {
t.Fatalf("linked_prs payload lacks the fields: %s", raw)
}

pr402 := trackerItem(t, resp, "pr", 402)
if pr402.HumanMergeReason != "policy" || !strings.Contains(pr402.HumanMergeReasonText, "`no-such-lane-reason`") {
t.Fatalf("PR 402 fallback = reason %q text %q", pr402.HumanMergeReason, pr402.HumanMergeReasonText)
}
if soak := trackerItem(t, resp, "pr", 102); soak.HumanMergeReason != "" || soak.HumanMergeReasonText != "" {
t.Fatalf("PR 102 (095) must not carry a human-merge reason: %+v", soak)
}
}

func stageTrackerFixture(t *testing.T, now time.Time) (*Server, *stagelabels.Store) {
t.Helper()
s := newTestServer()
Expand Down
Loading
Loading