diff --git a/changelog.d/changed-15676-stage-tracker-split.md b/changelog.d/changed-15676-stage-tracker-split.md new file mode 100644 index 0000000000..8262175f4d --- /dev/null +++ b/changelog.d/changed-15676-stage-tracker-split.md @@ -0,0 +1 @@ +- Split the `stage_tracker_decision.go` and `stage_tracker_merge_train.go` merge hotspots in `src/pkg/dashboard` into four files each (`stage_tracker_decision_{lanes,human_merge,pr}.go`, `stage_tracker_merge_train_{overlap,postpass,eta}.go`). Pure move of whole top-level declarations within the same package; no behaviour change and no exported API change. (#15676, #15678) diff --git a/src/pkg/dashboard/stage_tracker_decision.go b/src/pkg/dashboard/stage_tracker_decision.go index d6e61af942..32a11a7126 100644 --- a/src/pkg/dashboard/stage_tracker_decision.go +++ b/src/pkg/dashboard/stage_tracker_decision.go @@ -1,18 +1,11 @@ package dashboard import ( - "fmt" "slices" - "strconv" "strings" "time" - "unicode" - "github.com/hivecommons/hive/pkg/delegatedecision" - "github.com/hivecommons/hive/pkg/rebasemerge" "github.com/hivecommons/hive/pkg/review" - "github.com/hivecommons/hive/pkg/stageengine" - stageengineprstage "github.com/hivecommons/hive/pkg/stageengine/prstage" "github.com/hivecommons/hive/pkg/stagelabels" ) @@ -258,779 +251,3 @@ func stageTrackerWithoutHold(it StageTrackerItem) StageTrackerItem { it.Modifiers = slices.DeleteFunc(slices.Clone(it.Modifiers), func(m string) bool { return m == modHold }) return it } - -// decisionDelegateOption is "Let hive decide" for a state the hive would -// not otherwise decide: the delegate answers in plain words why it won't -// act itself and lists the person's options (hivecommons/hive#15078). -func decisionDelegateOption(held bool, consequence string) StageTrackerDecisionOption { - o := decisionOption(decisionActionDelegate, "Let hive decide", !held, decisionWhyHeld) - o.Consequence = consequence - return o -} - -// decisionForParked is the fallback for any needs-human state without a -// dedicated decision: say what the row is parked on and offer the generic -// moves — look again, hold, flag for a person (hivecommons/hive#15078). -func decisionForParked(it StageTrackerItem, held bool) *StageTrackerDecision { - what := "issue" - if it.Kind == "pr" { - what = "PR" - } - stage := strings.TrimSpace(it.StageLabel) - if stage == "" { - stage = "stage " + strconv.Itoa(it.Stage) - } - d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByLane, BlockerReason: strings.TrimSpace(it.Reason)} - d.Question = "This " + what + " sits at " + stage + ", a stage the hive leaves to a person" - if clause := decisionPlainReason(strings.TrimSpace(it.Reason)); strings.TrimSpace(it.Reason) != "" { - d.Question += " (" + clause + ")" - } - d.Question += ". Act on it on GitHub, then re-evaluate so the hive picks it up." - d.Blocker = "The hive makes no move here until a person does." - if held { - d.Blocker += " " + decisionHeldBlocker(it.Hold) - } - retry := decisionOption(decisionActionRetry, "Re-evaluate now", true, "") - retry.Consequence = "Re-reads GitHub and recomputes the stage" - d.Options = []StageTrackerDecisionOption{retry, decisionDelegateOption(held, "Hive explains what it can do here"), decisionHoldOption(held)} - if !slices.Contains(it.Modifiers, modNeedsHuman) { - d.Options = append(d.Options, decisionOption(decisionActionNeedsHuman, "Mark needs-human", true, "")) - } - return d -} - -// decisionForHumanMerge: a PR parked at 090 Ready for human merge — the -// hive's lanes will not merge it unattended (untrusted author, workflow -// files, manual-merge path, branch protection, …), so the person is asked -// to merge. The lead option is "Approve and let hive merge" -// (hivecommons/hive#15078): the maintainer has the last word, and the -// default way to use it is to approve and let the hive perform the merge -// through its own App — the merge sweep picks it up on its next tick once -// CI is green, soak and the self-merge ban still apply, and the merge is -// attributed to the approver. "Merge now as maintainer" merges at once -// through the App and stays available, but second. Both need the merger -// or owner role; the SPA greys them out for anyone else. -func decisionForHumanMerge(it StageTrackerItem, held bool) *StageTrackerDecision { - base, approver := stagelabels.HumanApprovedReason(it.Reason) - base = strings.TrimSpace(base) - _, _, tip := stageTrackerHumanMergeReason(it.Reason) - d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByLane, BlockerReason: base} - ref := "#" + strconv.Itoa(it.Number) - // First read: one sentence of state, one of why (hivecommons/hive#15394). - why := stageTrackerUntrustedAuthorWhy(base, it.Author) - fix := stageTrackerUntrustedAuthorFix(base, it.Author) - switch { - case why != "": - why = "Hive won't merge it alone — " + why + "." - case tip != "": - why = sentence(tip) - default: - why = "Hive's merge rules leave this one to a person." - } - d.Question = "Ready to merge. " + why - details := []string{"Hive never merges this on its own; a maintainer merges here or on GitHub."} - if fix != "" { - details = append(details, fix) - } - if approver != "" { - details = append(details, "Approved by @"+approver+".") - } - admitter := stagelabels.AdmissionLogin(it.AdmittedBy) - breaking := strings.EqualFold(base, stageengineprstage.AutoMergeReasonHumanMergeRequired) - if breaking { - // No approval lets hive merge a breaking change (hivecommons/hive#15442). - admitter = "" - } - if admitter != "" { - // A person already took the trust call for this head (#15136): - // the lane merges it as-is; nothing is adopted or re-authored. - d.Question = "@" + admitter + " approved it. Hive merges it on its next pass." - details = []string{"Admitted by @" + admitter + " (" + it.AdmittedBy + "). Hive merges this exact version once CI is green; a new push asks again."} - } - if dco := decisionDCOBlocker(it); dco != "" { - details = append(details, dco) - } - if held { - details = append(details, decisionHeldBlocker(it.Hold)) - } - d.Detail = stageTrackerSayOnce(d.Question, details...) - mergeNow := decisionMergeNowOption(it, held) - queue := decisionOption(decisionActionQueueMerge, decisionQueueMergeLabel, !held, "Release the hold first") - queue.Consequence = "Hive merges " + ref + " on its next tick once CI is green" - if admitter != "" && !held { - queue.Enabled, queue.ReasonIfDisabled = false, "@"+admitter+" already approved it; hive merges it next pass" - } - if breaking { - // The lanes skip a breaking-titled / needs-owner-merge PR however - // it is queued (hivecommons/hive#15442): the merge-now click is the - // one path, so queueing is offered greyed with the reason. - queue.Enabled, queue.ReasonIfDisabled = false, "Hive never merges a breaking change; merge it now as maintainer" - } - if it.DCOUnsigned > 0 { - mergeNow.Consequence += "; " + decisionDCOConsequence(it) - queue.Consequence += "; " + decisionDCOConsequence(it) - } - direction := decisionOption(decisionActionDirection, "Give direction", it.AuthorKind != authorKindHuman, "Hive did not open this PR, so it cannot carry a direction to its author; leave a review on GitHub") - direction.Consequence = "Asks the author's agent for changes instead" - closeSup := decisionOption(decisionActionCloseSuperseded, "Close as superseded", true, "") - closeSup.Consequence = "Closes " + ref + ", naming the PR that replaces it" - closeWontfix := decisionOption(decisionActionCloseWontfix, "Close as won't fix", true, "") - closeWontfix.Consequence = "Closes " + ref + " without merging" - delegate := decisionDelegateOption(held, "Hive explains and recommends; merges nothing") - d.Options = decisionHumanMergeLeadOptions(mergeNow, queue) - if it.DCOUnsigned > 0 { - d.Options = append(d.Options, decisionReauthorOption(it, ref, held)) - } - d.Options = append(d.Options, delegate, direction, closeSup, closeWontfix, decisionHoldOption(held)) - return d -} - -// decisionQueueMergeLabel is the lead merge-gate answer on a 090 row: the -// maintainer approves and the hive's merge sweep merges on its next tick. -const decisionQueueMergeLabel = "Approve and let hive merge" - -// decisionMergeNowLabel is the secondary answer: merge at once through the -// hive's App, attributed to the maintainer. -const decisionMergeNowLabel = "Merge now as maintainer" - -// decisionHumanMergeLeadOptions orders the two merge-gate answers: "Approve -// and let hive merge" leads whenever it can be clicked; only when queueing -// is greyed out (a breaking change the lanes never merge, a head somebody -// already admitted) does "Merge now as maintainer" step forward, so the -// lead is never a button nobody can press. -func decisionHumanMergeLeadOptions(mergeNow, queue StageTrackerDecisionOption) []StageTrackerDecisionOption { - if !queue.Enabled && mergeNow.Enabled { - return []StageTrackerDecisionOption{mergeNow, queue} - } - return []StageTrackerDecisionOption{queue, mergeNow} -} - -// stageTrackerSayOnce joins parts into one text, dropping any sentence -// that already appeared in lead or earlier in the parts, so a hover never -// says the same thing twice (hivecommons/hive#15394). -func stageTrackerSayOnce(lead string, parts ...string) string { - seen := map[string]bool{} - for _, sent := range stageTrackerSentences(lead) { - seen[sent] = true - } - var out []string - for _, part := range parts { - var keep []string - for _, sent := range stageTrackerSentences(part) { - if seen[sent] { - continue - } - seen[sent] = true - keep = append(keep, sentence(sent)) - } - if len(keep) > 0 { - out = append(out, strings.Join(keep, " ")) - } - } - return strings.Join(out, " ") -} - -// stageTrackerSentences splits text on sentence ends and normalises each -// sentence (trimmed, trailing punctuation dropped, lower-cased first rune) -// for say-it-once comparison. -func stageTrackerSentences(text string) []string { - var out []string - for _, raw := range strings.FieldsFunc(text, func(r rune) bool { return r == '.' || r == '?' || r == '!' }) { - raw = strings.TrimSpace(raw) - if raw == "" { - continue - } - r := []rune(raw) - r[0] = unicode.ToLower(r[0]) - out = append(out, string(r)) - } - return out -} - -// sentence capitalises a clause and ends it with a full stop. -func sentence(s string) string { - s = strings.TrimSpace(s) - if s == "" { - return "" - } - r := []rune(s) - r[0] = unicode.ToUpper(r[0]) - s = string(r) - if !strings.HasSuffix(s, ".") && !strings.HasSuffix(s, "?") && !strings.HasSuffix(s, "!") { - s += "." - } - return s -} - -// decisionDCOBlocker says, before anyone presses Approve, that the head -// cannot merge as-is where DCO is required: the stage record's commit check -// found commits without a Signed-off-by (hivecommons/hive#15136). "" when -// the check is not cached for this head or every commit is signed. -func decisionDCOBlocker(it StageTrackerItem) string { - if it.DCOUnsigned <= 0 { - return "" - } - return fmt.Sprintf("%d of %s no Signed-off-by, so a required DCO check refuses the merge. Re-author as hive PR is the separate choice for that; an Approve never re-authors by itself.", - it.DCOUnsigned, pluralCommitsHave(it.DCOTotal)) -} - -// decisionDCOConsequence is the short DCO caveat under the merge options. -func decisionDCOConsequence(it StageTrackerItem) string { - return fmt.Sprintf("%d of %s no Signed-off-by (DCO)", it.DCOUnsigned, pluralCommitsHave(it.DCOTotal)) -} - -// pluralCommitsHave renders "3 commits have" / "1 commit has" for the DCO -// sentences; a total the record does not know reads "its commits have". -func pluralCommitsHave(total int) string { - switch { - case total == 1: - return "1 commit has" - case total > 1: - return strconv.Itoa(total) + " commits have" - } - return "its commits have" -} - -// decisionReauthorOption is the operator's explicit "re-author as hive PR" -// choice (hivecommons/hive#15136): the hive re-homes the commits on a -// hive-owned, signed-off branch and opens a superseding PR. A person's PR -// is never re-authored by the hive, so for a human author the option is -// shown disabled with the step that does unblock it. -func decisionReauthorOption(it StageTrackerItem, ref string, held bool) StageTrackerDecisionOption { - o := decisionOption(decisionActionReauthor, "Re-author as hive PR", !held && it.AuthorKind != authorKindHuman, "Release the hold first") - if it.AuthorKind == authorKindHuman { - who := "the author" - if it.Author != "" { - who = "@" + it.Author - } - o.ReasonIfDisabled = "Hive does not re-author a person's PR; ask " + who + " to sign off and push" - } - o.Consequence = "Hive reopens " + ref + " as a signed-off hive PR; nothing is merged as-is" - return o -} - -// decisionMergeNowOption is "Merge now as maintainer", or — when the row -// wears needs-rebase, so a plain merge would be a GitHub 405 — "Rebase, -// then merge as maintainer": the same click records the approval, has the -// hive rebase the PR, and merges it on green (hivecommons/hive#14822). -// Either way it is the secondary answer behind "Approve and let hive merge". -func decisionMergeNowOption(it StageTrackerItem, held bool) StageTrackerDecisionOption { - ref := "#" + strconv.Itoa(it.Number) - into := strings.TrimSpace(it.BaseRef) - if into == "" { - into = "its base branch" - } - if stageTrackerNeedsRebase(it) { - opt := decisionOption(decisionActionMergeNow, rebaseMergeFollowThroughLabel, !held, "Release the hold first") - opt.Consequence = rebaseMergeFollowThroughConsequence(it.Number, strings.TrimSpace(it.BaseRef)) - return opt - } - opt := decisionOption(decisionActionMergeNow, decisionMergeNowLabel, !held, "Release the hold first") - opt.Consequence = "Merges " + ref + " into " + into + " now, credited to you" - return opt -} - -// stageTrackerNeedsRebase: the row wears needs-rebase (modifier or label), -// or a rebase-then-merge follow-through is already running on it. -func stageTrackerNeedsRebase(it StageTrackerItem) bool { - if slices.Contains(it.Modifiers, modNeedsRebase) { - return true - } - for _, l := range it.Labels { - if strings.EqualFold(strings.TrimSpace(l), "needs-rebase") { - return true - } - } - return it.RebaseMerge != nil && it.RebaseMerge.State != "" && it.RebaseMerge.State != "merged" && it.RebaseMerge.State != "failed" -} - -// decisionForUnauthorized: a row wearing hive:unauthorized outside 085 — -// the hive's GitHub App lacks the permission for its next step, so a -// person takes that step on GitHub (approve the held workflow runs, merge -// the workflow-file PR, …) and then asks the hive to look again. -func decisionForUnauthorized(it StageTrackerItem, held bool) *StageTrackerDecision { - d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByApp, BlockerReason: strings.TrimSpace(it.Reason)} - step := strings.TrimSpace(it.UnauthorizedStep) - if step == "" { - _, tip := stageTrackerUnauthorized(it.Reason) - d.Question = "The hive's GitHub App lacks a permission for the next step. " + tip - } else { - d.Question = "The hive's GitHub App may not " + unauthorizedStepWords(step) + " here. Do that step on GitHub, then re-evaluate so the hive picks it up." - } - d.Blocker = strings.TrimSpace(it.Unauthorized) - if d.Blocker == "" { - d.Blocker = decisionWhyNoPermission + "." - } - if held { - d.Blocker += " " + decisionHeldBlocker(it.Hold) - } - retry := decisionOption(decisionActionRetry, "Re-evaluate now", true, "") - retry.Consequence = "Re-reads GitHub; hive resumes once the step is done" - d.Options = []StageTrackerDecisionOption{retry, decisionDelegateOption(held, "Hive explains which step it may not take"), decisionHoldOption(held)} - if !slices.Contains(it.Modifiers, modNeedsHuman) { - d.Options = append(d.Options, decisionOption(decisionActionNeedsHuman, "Mark needs-human", true, "")) - } - return d -} - -// decisionForWaitingOnAuthor: a human-authored PR at 071 Needs author / -// 072 Returned to contributor — the hive waits for its author to push. -// The hive never adopts a human's PR, so the person's choices are to wait, -// hold, or close it (hivecommons/hive#15078). -func decisionForWaitingOnAuthor(it StageTrackerItem, held bool) *StageTrackerDecision { - who := "its author" - if a := strings.TrimSpace(it.Author); a != "" { - who = "@" + a - } - ref := "#" + strconv.Itoa(it.Number) - d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByLane, BlockerReason: strings.TrimSpace(it.Reason)} - what := "a new commit" - if clause := decisionPlainReason(strings.TrimSpace(it.Reason)); strings.TrimSpace(it.Reason) != "" && clause != "the hive parked it" { - what = "a new commit (" + clause + ")" - } - d.Question = "This PR waits on " + who + " to push " + what + ". The hive never rewrites a person's PR; it waits unless you say otherwise." - d.Blocker = "Nothing for the hive to do until " + who + " pushes." - if held { - d.Blocker += " " + decisionHeldBlocker(it.Hold) - } - closeSup := decisionOption(decisionActionCloseSuperseded, "Close as superseded", true, "") - closeSup.Consequence = "Closes " + ref + ", naming the PR that replaces it" - closeWontfix := decisionOption(decisionActionCloseWontfix, "Close as won't fix", true, "") - closeWontfix.Consequence = "Closes " + ref + " without merging" - d.Options = []StageTrackerDecisionOption{decisionDelegateOption(held, "Hive weighs waiting against closing; never rewrites the PR"), closeSup, closeWontfix, decisionHoldOption(held)} - return d -} - -// decisionForWaitingOnContributor: a 072 clanker PR whose adoption came due -// and is held (hivecommons/hive#15038). The options are the takeover's. -func decisionForWaitingOnContributor(it StageTrackerItem, held bool, now time.Time) *StageTrackerDecision { - a := it.Adoption - who := "the author" - if a.Author != "" { - who = "@" + a.Author - } - d := &StageTrackerDecision{Since: a.Since, AskedBy: decisionAskedByLane, BlockerReason: "adoption:" + a.BlockerReason()} - gone := "has been offline since the nudge" - if off := strings.TrimSpace(stageTrackerAdoptionOfflineFor(*a, now)); off != "" { - gone = "has been offline for " + off - } - if a.AuthorOnline { - gone = "is online but has not answered " + plural(a.Nudges, "nudge") - } - d.Question = who + " " + gone + " and the hive is not adopting on its own; take the PR over now, or reroute its follow-up work to another clanker?" - d.Blocker = "The PR waits on " + who + "'s hive; adoption is held (" + a.BlockerReason() + ")." - if held { - d.Blocker += " " + decisionHeldBlocker(it.Hold) - } - d.Options = append(takeoverDecisionOptions(it.Takeover, held), decisionHoldOption(held)) - return d -} - -// decisionForAdoption: a nudged 072 PR whose author maintains the -// repository, held for an owner under -// governor.labels.stage.adoption.maintainer_policy: ask -// (hivecommons/hive#14524). The question names the author and how long -// their clanker has been gone; the lead option is Adopt. -func decisionForAdoption(it StageTrackerItem, held bool, now time.Time) *StageTrackerDecision { - a := it.Adoption - who := "the author" - if a.Author != "" { - who = "@" + a.Author - } - d := &StageTrackerDecision{Since: a.Since, AskedBy: decisionAskedByLane, BlockerReason: "adoption:" + a.BlockedBy} - gone := "has been offline since the nudge" - if off := strings.TrimSpace(stageTrackerAdoptionOfflineFor(*a, now)); off != "" { - gone = "has been offline for " + off - } - if a.AuthorOnline { - gone = "is online but has not answered " + plural(a.Nudges, "nudge") - } - d.Question = who + " maintains this repository and " + gone + "; adopt the PR? The hive would take it over as it does any contributor's (the author's commits and sign-off are kept)." - d.Blocker = "maintainer_policy is ask: the hive never adopts a maintainer's PR on its own; a person decides." - if held { - d.Blocker += " " + decisionHeldBlocker(it.Hold) - } - d.Options = []StageTrackerDecisionOption{ - decisionOption(decisionActionAdopt, "Adopt (hive takes over)", !held, "Release the hold first"), - } - d.Options = append(d.Options, takeoverDecisionOptions(it.Takeover, held)...) - d.Options = append(d.Options, decisionHoldOption(held)) - return d -} - -func decisionHoldOption(held bool) StageTrackerDecisionOption { - if held { - return StageTrackerDecisionOption{Action: decisionActionRelease, Label: "Release hold", Enabled: true} - } - return StageTrackerDecisionOption{Action: decisionActionHold, Label: "Hold", Enabled: true} -} - -func decisionOption(action, label string, enabled bool, why string) StageTrackerDecisionOption { - if enabled { - why = "" - } - return StageTrackerDecisionOption{Action: action, Label: label, Enabled: enabled, ReasonIfDisabled: why} -} - -// decisionChangesRequested reports whether the base reason says a swarm -// reviewer asked for changes — directly, or as the lane reason an adoption -// stalled on. -func decisionChangesRequested(base string) bool { - lower := strings.ToLower(strings.TrimSpace(base)) - lower = strings.TrimPrefix(lower, stagelabels.LaneReasonAdoptionStalledPrefix) - switch lower { - case stageengineprstage.ContributorLaneReasonChangesRequested, stagelabels.LaneReasonChangesRequested, - "reviewer-verdict:request_changes", "changes-requested", stageengineprstage.AutoMergeReasonHumanChangesRequested: - return true - } - return false -} - -// decisionLaneRule reports whether the base reason is a lane rule that -// never merges unattended whoever approves (workflow files, removed tests, -// human-merge paths, no reviewer, refused merges, …). -func decisionLaneRule(base string) bool { - lower := strings.ToLower(strings.TrimSpace(base)) - switch lower { - case stageengineprstage.ContributorLaneReasonWorkflowPath, stageengineprstage.ContributorLaneReasonTestsRemoved, - stageengineprstage.ContributorLaneReasonNoReviewer, stageengineprstage.ContributorLaneReasonReporterTrustHold, - stageengineprstage.ContributorLaneReasonNoAppBotLogin, stageengineprstage.ContributorLaneReasonFilesEvidence, - stageengineprstage.AutoMergeReasonHumanMergePath, stageengineprstage.AutoMergeReasonHumanMergePathEvidence, - stageengineprstage.AutoMergeReasonIntentUnauthorized, stageengineprstage.AutoMergeReasonIntentEvidence, - stageengineprstage.AutoMergeReasonMergeRefusedReview, stageengineprstage.AutoMergeReasonMergeRefusedMethod, - stageengineprstage.AutoMergeReasonNoAppBotLogin, stageengineprstage.AutoMergeReasonHumanMergeRequired: - return true - } - return false -} - -// decisionPlainReason renders a lane rule in plain words for the popover -// (the owner's bar: no reason slugs, no stage codes, no hive jargon). -func decisionPlainReason(base string) string { - switch strings.ToLower(strings.TrimSpace(base)) { - case stageengineprstage.ContributorLaneReasonWorkflowPath: - return "it edits CI workflow files" - case stageengineprstage.ContributorLaneReasonTestsRemoved: - return "it removes tests" - case stageengineprstage.ContributorLaneReasonNoReviewer: - return "no reviewer is configured for this repo" - case stageengineprstage.ContributorLaneReasonReporterTrustHold: - return "the hive held it for the trust level of the linked issue's reporter" - case stageengineprstage.ContributorLaneReasonNoAppBotLogin, stageengineprstage.AutoMergeReasonNoAppBotLogin: - return "the hive's GitHub App login is not known" - case stageengineprstage.ContributorLaneReasonFilesEvidence: - return "the hive could not read its changed files" - case stageengineprstage.AutoMergeReasonHumanMergePath, stageengineprstage.AutoMergeReasonHumanMergePathEvidence: - return "it touches files a person must merge" - case stageengineprstage.AutoMergeReasonHumanMergeRequired: - return "it is a breaking change (⚠️ title or needs-owner-merge label) — the owner merges it" - case stageengineprstage.AutoMergeReasonIntentUnauthorized, stageengineprstage.AutoMergeReasonIntentEvidence: - return "the hive could not confirm the author's merge intent" - case stageengineprstage.AutoMergeReasonMergeRefusedReview: - return "GitHub requires a review the hive cannot give" - case stageengineprstage.AutoMergeReasonMergeRefusedMethod: - return "GitHub refused the hive's merge method" - } - // The shared decision glossary (pkg/delegatedecision) covers the - // reasons the lane shares with the delegate — changes requested, - // sentinel, conflicts, red CI, DCO — in the same words the toast and - // the PR comment use (hivecommons/hive#14822). - if e, ok := delegatedecision.Explain(base); ok && e.Kind == delegatedecision.GlossaryReason { - return e.Plain - } - if text := humanizeStageReason(base); text != "" { - return text - } - return "the hive parked it" -} - -func decisionForPR(it StageTrackerItem, verdict *review.Aggregate, sentinelLabel string, held bool) *StageTrackerDecision { - base, _ := stagelabels.HumanApprovedReason(it.Reason) - base = strings.TrimSpace(base) - lower := strings.ToLower(base) - sha := shortHead(it.Head) - at := "" - if sha != "" { - at = " on " + sha - } - d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByLane, BlockerReason: base} - approveOK, approveWhy := true, "" - delegateOK, delegateWhy := !held, decisionWhyHeld - var selfHold *StageTrackerHold - if held && it.Hold != nil && strings.EqualFold(it.Hold.By, stagelabels.HoldByHive) && it.Hold.Source != "" && it.Hold.Source != stagelabels.HoldSourceLabel { - selfHold = it.Hold - } - - sentinel := it.SentinelAlert || lower == "sentinel" || lower == stageengineprstage.ContributorLaneReasonSentinelBlocked - changes := decisionChangesRequested(base) - laneRule := decisionLaneRule(base) - adoptionLane, adoptionStalled := strings.CutPrefix(base, stagelabels.LaneReasonAdoptionStalledPrefix) - forkGuard, forkGuarded := strings.CutPrefix(base, stageengineprstage.StageReasonForkGuard) - // hivecommons/hive#15307: the hive's adoption copy (or the original it - // supersedes) after the fixer's two rebase-resolve attempts failed. - rebaseFailedTwice := lower == stagelabels.LaneReasonRebaseFailedTwice || (adoptionStalled && adoptionLane == stagelabels.LaneReasonRebaseFailedTwice) - reviewerDeferred := lower == stageengine.StageReasonVerdictRequiresHuman || lower == stageengine.StageReasonDecisionRequested - - // WHAT it is waiting on: the question, most specific source first. A - // reviewer's own question is quoted verbatim — it is the text the - // hive's "Needs a decision" comment on the PR prints after "reviewer - // question:", read from the same verdict record. - switch { - case it.UnauthorizedStep != "": - d.AskedBy = decisionAskedByApp - d.Question = "The hive's GitHub App may not " + unauthorizedStepWords(it.UnauthorizedStep) + " here. A maintainer has to do that step on GitHub." - d.Blocker = strings.TrimSpace(it.Unauthorized) - delegateOK, delegateWhy = false, decisionWhyNoPermission - approveOK, approveWhy = false, decisionWhyApproveNoGrant - case verdict != nil && strings.TrimSpace(verdict.DecisionQuestion) != "": - d.AskedBy = decisionAskedByReviewer - d.Question = strings.TrimSpace(verdict.DecisionQuestion) - if !verdict.RecordedAt.IsZero() { - t := verdict.RecordedAt - d.Since = &t - } - case verdict != nil && verdict.RedundantOf > 0: - d.AskedBy = decisionAskedByReviewer - d.Question = "A reviewer found this PR's change already on the base through #" + strconv.Itoa(verdict.RedundantOf) + ". Close it as superseded, or give direction?" - if !verdict.RecordedAt.IsZero() { - t := verdict.RecordedAt - d.Since = &t - } - case selfHold != nil: - // The hive held the PR itself (hivecommons/hive#15020): say so, - // name the gate and the issue, and offer release / keep. - d.AskedBy = decisionAskedByLane - d.Question = "The hive held this PR itself for " + decisionHoldReason(selfHold) + ". Release the hold (the lane then merges it on its next pass once the other gates are clear), or keep it?" - if selfHold.Since != nil { - t := *selfHold.Since - d.Since = &t - } - d.Blocker = "The hive set `hold` on its own: " + decisionHoldReason(selfHold) + ". It does nothing more until the hold is released." - d.BlockerReason = decisionBlockerHoldHive - case verdict != nil && decisionFirstNonEmpty(verdict.HumanSummaries) != "": - d.AskedBy = decisionAskedByReviewer - d.Question = "A reviewer handed this to a person: " + decisionFirstNonEmpty(verdict.HumanSummaries) - if !verdict.RecordedAt.IsZero() { - t := verdict.RecordedAt - d.Since = &t - } - case reviewerDeferred: - d.AskedBy = decisionAskedByReviewer - d.Question = "A reviewer handed this PR to a person without a specific question. Merge it as is, give direction, or close it?" - case sentinel: - d.AskedBy = decisionAskedBySentinel - reason := strings.TrimSpace(it.SentinelReason) - if reason == "" { - reason = "security-relevant changes" - } - d.Question = "The security check flagged " + reason + at + ". Accept it as is, give direction, or close it?" - case lower == stagelabels.LaneReasonAdoptionChildClosedTwice: - d.Question = "The hive's copies of this PR were closed without merging twice within an hour, so the hive stopped opening copies. Reopen the last copy (#" + strconv.Itoa(it.AdoptedBy) + "), give direction, or close it?" - case rebaseFailedTwice: - d.Question = "The hive adopted this PR but its fixer could not resolve the conflicts with the base in two attempts. Adopt the commits into a fresh branch, give direction, or close it as superseded?" - case lower == stagelabels.LaneReasonAdoptionCopyFailed: - d.Question = "The hive's copy of this PR (#" + strconv.Itoa(it.AdoptedBy) + ") failed, so this PR was reopened. Ask the hive to supersede it again, give direction, or close it?" - case adoptionStalled: - d.Question = "The hive took this PR over but could not move it (" + decisionPlainReason(adoptionLane) + "). Give direction, or close it?" - case forkGuarded: - d.Question = "CI will not run for this fork PR (" + strings.ReplaceAll(forkGuard, ",", ", ") + "). A maintainer must push the branch to this repo — or close it?" - case changes: - d.AskedBy = decisionAskedByReviewer - d.Question = "A reviewer requested changes" + at + ". Give direction for a new commit, or close it?" - case laneRule: - d.Question = "The hive never merges this by itself (" + decisionPlainReason(base) + "). Approve it for a maintainer to merge, give direction, or close it?" - default: - clause := decisionPlainReason(base) - if base == "" { - clause = strings.TrimSpace(it.Caption) - } - if clause == "" { - clause = "the hive parked it" - } - d.Question = "A person must decide (" + clause + "). Approve, give direction, or close?" - } - - // The blocker in plain words, and what it disables. - switch { - case it.UnauthorizedStep != "": - // set above - case changes: - d.Blocker = "A reviewer requested changes" + at + " — needs a new commit. Approving cannot override that." - approveOK, approveWhy = false, d.Blocker - case sentinel: - d.Blocker = "The security check has an open alert. The hive will not merge until a person removes the `" + sentinelLabel + "` label." - if base == "" { - d.BlockerReason = decisionBlockerSentinel - } - case laneRule: - d.Blocker = "The hive never merges this by itself. After approval, a maintainer merges." - case forkGuarded: - d.Blocker = "Neither the author nor the hive can make CI run for this fork PR." - case reviewerDeferred: - d.Blocker = "The hive will not merge until a person decides." - if verdict != nil && strings.TrimSpace(verdict.DecisionFinding) != "" { - d.Blocker = "The review found: " + strings.TrimSpace(verdict.DecisionFinding) + ". " + d.Blocker - } - } - if held && selfHold == nil { - if d.Blocker != "" { - d.Blocker += " " - } - d.Blocker += decisionHeldBlocker(it.Hold) - if d.BlockerReason == "" { - d.BlockerReason = decisionBlockerHold - } - } - - d.Options = []StageTrackerDecisionOption{ - decisionOption(decisionActionDelegate, "Let hive decide", delegateOK, delegateWhy), - decisionOption(decisionActionApprove, "Approve", approveOK, approveWhy), - decisionOption(decisionActionDirection, "Give direction", true, ""), - decisionOption(decisionActionCloseSuperseded, "Close as superseded", true, ""), - decisionOption(decisionActionCloseWontfix, "Close as won't fix", true, ""), - decisionHoldOption(held), - } - // A PR parked here that also needs a rebase has no lane rebasing it - // until a person speaks (hivecommons/hive#14822): offer the maintainer - // merge with the rebase folded in, right after Approve. - if stageTrackerNeedsRebase(it) && !sentinel { - d.Options = slices.Insert(d.Options, 2, decisionMergeNowOption(it, held)) - } - if rebaseFailedTwice { - // The two answers to a rebase nobody could finish lead, as they do - // for merge-now (rebaseMergeFailureOptions). - d.Options = slices.Insert(d.Options, 0, decisionOption(decisionActionAdopt, rebasemerge.OptionAdoptFreshLabel, true, "")) - } - if selfHold != nil { - // Release leads: it is the one action that answers the question. - d.Options = append([]StageTrackerDecisionOption{decisionHoldOption(true)}, d.Options[:len(d.Options)-1]...) - } - if verdict != nil && verdict.RedundantOf > 0 && selfHold == nil { - // The reviewer named the PR that already carries this change - // (hivecommons/hive#15499): closing as superseded is the answer - // to that question, so it leads and says which PR. - d.RedundantOf = verdict.RedundantOf - d.Options = decisionLeadWithCloseSuperseded(d.Options, verdict.RedundantOf) - } - return d -} - -// decisionLeadWithCloseSuperseded moves "Close as superseded" to the front -// of opts with the superseding PR named in its consequence. -func decisionLeadWithCloseSuperseded(opts []StageTrackerDecisionOption, redundantOf int) []StageTrackerDecisionOption { - lead := decisionOption(decisionActionCloseSuperseded, "Close as superseded", true, "") - lead.Consequence = "Closes this PR as superseded by #" + strconv.Itoa(redundantOf) + ", which already carries its change." - lead.Lead = true - out := make([]StageTrackerDecisionOption, 0, len(opts)+1) - out = append(out, lead) - for _, o := range opts { - if o.Action == decisionActionCloseSuperseded { - continue - } - out = append(out, o) - } - return out -} - -// decisionHoldReason is the hold's plain-words reason for the popover. -func decisionHoldReason(h *StageTrackerHold) string { - if h != nil { - if reason := strings.TrimSpace(h.Reason); reason != "" { - return reason - } - } - return "its own gate" -} - -// decisionHeldBlocker is the "On hold" blocker sentence, naming who set the -// hold when the row knows (hivecommons/hive#15020). -func decisionHeldBlocker(h *StageTrackerHold) string { - if h == nil || strings.TrimSpace(h.By) == "" { - return decisionHeldBlockerPlain - } - who := "@" + strings.TrimSpace(h.By) - if strings.EqualFold(h.By, stagelabels.HoldByHive) { - who = "the hive" - } - s := "On hold (set by " + who - if reason := strings.TrimSpace(h.Reason); reason != "" { - s += ": " + reason - } - return s + ") — the hive does nothing until the hold is released." -} - -func decisionForIssue(it StageTrackerItem, held bool) *StageTrackerDecision { - d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByHiveAgent, BlockerReason: strings.TrimSpace(it.Reason)} - d.Question = "The hive parked this issue for a person. Approve the direction, send it back with direction, or close it?" - d.Blocker = "No agent picks this up until a person answers. The hive's question is in its latest comment on the issue." - if held { - d.Blocker += " " + decisionHeldBlocker(it.Hold) - if d.BlockerReason == "" { - d.BlockerReason = decisionBlockerHold - } - } - d.Options = []StageTrackerDecisionOption{ - decisionOption(decisionActionDelegate, "Let hive decide", !held, decisionWhyHeld), - decisionOption(decisionActionApprove, "Approve direction", true, ""), - decisionOption(decisionActionDirection, "Send back", true, ""), - decisionOption(decisionActionCloseSuperseded, "Close as superseded", true, ""), - decisionOption(decisionActionCloseWontfix, "Close as won't fix", true, ""), - decisionHoldOption(held), - } - return d -} - -func decisionForTriage(it StageTrackerItem, held bool) *StageTrackerDecision { - d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByTriage, BlockerReason: strings.TrimSpace(it.Reason)} - d.Question = "Should the hive work on this issue? Accept triage so an agent can take it, hold it, or mark it needs-human." - d.Blocker = "No agent picks up an issue until a maintainer accepts triage." - if held { - d.Blocker += " " + decisionHeldBlocker(it.Hold) - } - d.Options = []StageTrackerDecisionOption{ - decisionOption(decisionActionAcceptTriage, "Accept triage", true, ""), - decisionDelegateOption(held, "Hive triages it for you, or explains why not"), - decisionHoldOption(held), - } - if !slices.Contains(it.Modifiers, modNeedsHuman) { - d.Options = append(d.Options, decisionOption(decisionActionNeedsHuman, "Mark needs-human", true, "")) - } - return d -} - -func decisionForNeedsHuman(it StageTrackerItem, held bool) *StageTrackerDecision { - d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByEscalation, BlockerReason: "label:" + modNeedsHuman} - what := "issue" - if it.Kind == "pr" { - what = "PR" - } - d.Question = "This " + what + " is marked needs-human: automated fixes ran out, or a person flagged it. Review it, then resolve it here (lifts the label) or remove the label on GitHub when the hive may continue." - d.Blocker = "The hive does nothing with a needs-human item until a person removes the label." - if held { - d.Blocker += " " + decisionHeldBlocker(it.Hold) - } - // The matching action for the ask (hivecommons/hive#15078): Approve - // lifts needs-human — on a PR it also posts /lgtm + /approve as the - // operator, on an issue it records /hive approve and un-parks it. - resolve := decisionOption(decisionActionApprove, "Resolve — lift needs-human", !held, "Release the hold first") - if it.Kind == "pr" { - resolve.Consequence = "Lifts needs-human and approves as you; hive merges" - } else { - resolve.Consequence = "Lifts needs-human and approves as you; hive carries on" - } - d.Options = []StageTrackerDecisionOption{resolve} - // A needs-human PR still waiting on its contributor's clanker offers - // the takeover actions too (hivecommons/hive#15038). - d.Options = append(d.Options, takeoverDecisionOptions(it.Takeover, held)...) - d.Options = append(d.Options, decisionDelegateOption(held, "Hive reviews it and lifts needs-human, or explains why not"), decisionHoldOption(held)) - return d -} - -func decisionFirstNonEmpty(ss []string) string { - for _, s := range ss { - if t := strings.TrimSpace(s); t != "" { - return t - } - } - return "" -} diff --git a/src/pkg/dashboard/stage_tracker_decision_human_merge.go b/src/pkg/dashboard/stage_tracker_decision_human_merge.go new file mode 100644 index 0000000000..9c710a2d10 --- /dev/null +++ b/src/pkg/dashboard/stage_tracker_decision_human_merge.go @@ -0,0 +1,257 @@ +package dashboard + +import ( + "fmt" + "slices" + "strconv" + "strings" + "unicode" + + stageengineprstage "github.com/hivecommons/hive/pkg/stageengine/prstage" + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// decisionForHumanMerge: a PR parked at 090 Ready for human merge — the +// hive's lanes will not merge it unattended (untrusted author, workflow +// files, manual-merge path, branch protection, …), so the person is asked +// to merge. The lead option is "Approve and let hive merge" +// (hivecommons/hive#15078): the maintainer has the last word, and the +// default way to use it is to approve and let the hive perform the merge +// through its own App — the merge sweep picks it up on its next tick once +// CI is green, soak and the self-merge ban still apply, and the merge is +// attributed to the approver. "Merge now as maintainer" merges at once +// through the App and stays available, but second. Both need the merger +// or owner role; the SPA greys them out for anyone else. +func decisionForHumanMerge(it StageTrackerItem, held bool) *StageTrackerDecision { + base, approver := stagelabels.HumanApprovedReason(it.Reason) + base = strings.TrimSpace(base) + _, _, tip := stageTrackerHumanMergeReason(it.Reason) + d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByLane, BlockerReason: base} + ref := "#" + strconv.Itoa(it.Number) + // First read: one sentence of state, one of why (hivecommons/hive#15394). + why := stageTrackerUntrustedAuthorWhy(base, it.Author) + fix := stageTrackerUntrustedAuthorFix(base, it.Author) + switch { + case why != "": + why = "Hive won't merge it alone — " + why + "." + case tip != "": + why = sentence(tip) + default: + why = "Hive's merge rules leave this one to a person." + } + d.Question = "Ready to merge. " + why + details := []string{"Hive never merges this on its own; a maintainer merges here or on GitHub."} + if fix != "" { + details = append(details, fix) + } + if approver != "" { + details = append(details, "Approved by @"+approver+".") + } + admitter := stagelabels.AdmissionLogin(it.AdmittedBy) + breaking := strings.EqualFold(base, stageengineprstage.AutoMergeReasonHumanMergeRequired) + if breaking { + // No approval lets hive merge a breaking change (hivecommons/hive#15442). + admitter = "" + } + if admitter != "" { + // A person already took the trust call for this head (#15136): + // the lane merges it as-is; nothing is adopted or re-authored. + d.Question = "@" + admitter + " approved it. Hive merges it on its next pass." + details = []string{"Admitted by @" + admitter + " (" + it.AdmittedBy + "). Hive merges this exact version once CI is green; a new push asks again."} + } + if dco := decisionDCOBlocker(it); dco != "" { + details = append(details, dco) + } + if held { + details = append(details, decisionHeldBlocker(it.Hold)) + } + d.Detail = stageTrackerSayOnce(d.Question, details...) + mergeNow := decisionMergeNowOption(it, held) + queue := decisionOption(decisionActionQueueMerge, decisionQueueMergeLabel, !held, "Release the hold first") + queue.Consequence = "Hive merges " + ref + " on its next tick once CI is green" + if admitter != "" && !held { + queue.Enabled, queue.ReasonIfDisabled = false, "@"+admitter+" already approved it; hive merges it next pass" + } + if breaking { + // The lanes skip a breaking-titled / needs-owner-merge PR however + // it is queued (hivecommons/hive#15442): the merge-now click is the + // one path, so queueing is offered greyed with the reason. + queue.Enabled, queue.ReasonIfDisabled = false, "Hive never merges a breaking change; merge it now as maintainer" + } + if it.DCOUnsigned > 0 { + mergeNow.Consequence += "; " + decisionDCOConsequence(it) + queue.Consequence += "; " + decisionDCOConsequence(it) + } + direction := decisionOption(decisionActionDirection, "Give direction", it.AuthorKind != authorKindHuman, "Hive did not open this PR, so it cannot carry a direction to its author; leave a review on GitHub") + direction.Consequence = "Asks the author's agent for changes instead" + closeSup := decisionOption(decisionActionCloseSuperseded, "Close as superseded", true, "") + closeSup.Consequence = "Closes " + ref + ", naming the PR that replaces it" + closeWontfix := decisionOption(decisionActionCloseWontfix, "Close as won't fix", true, "") + closeWontfix.Consequence = "Closes " + ref + " without merging" + delegate := decisionDelegateOption(held, "Hive explains and recommends; merges nothing") + d.Options = decisionHumanMergeLeadOptions(mergeNow, queue) + if it.DCOUnsigned > 0 { + d.Options = append(d.Options, decisionReauthorOption(it, ref, held)) + } + d.Options = append(d.Options, delegate, direction, closeSup, closeWontfix, decisionHoldOption(held)) + return d +} + +// decisionQueueMergeLabel is the lead merge-gate answer on a 090 row: the +// maintainer approves and the hive's merge sweep merges on its next tick. +const decisionQueueMergeLabel = "Approve and let hive merge" + +// decisionMergeNowLabel is the secondary answer: merge at once through the +// hive's App, attributed to the maintainer. +const decisionMergeNowLabel = "Merge now as maintainer" + +// decisionHumanMergeLeadOptions orders the two merge-gate answers: "Approve +// and let hive merge" leads whenever it can be clicked; only when queueing +// is greyed out (a breaking change the lanes never merge, a head somebody +// already admitted) does "Merge now as maintainer" step forward, so the +// lead is never a button nobody can press. +func decisionHumanMergeLeadOptions(mergeNow, queue StageTrackerDecisionOption) []StageTrackerDecisionOption { + if !queue.Enabled && mergeNow.Enabled { + return []StageTrackerDecisionOption{mergeNow, queue} + } + return []StageTrackerDecisionOption{queue, mergeNow} +} + +// stageTrackerSayOnce joins parts into one text, dropping any sentence +// that already appeared in lead or earlier in the parts, so a hover never +// says the same thing twice (hivecommons/hive#15394). +func stageTrackerSayOnce(lead string, parts ...string) string { + seen := map[string]bool{} + for _, sent := range stageTrackerSentences(lead) { + seen[sent] = true + } + var out []string + for _, part := range parts { + var keep []string + for _, sent := range stageTrackerSentences(part) { + if seen[sent] { + continue + } + seen[sent] = true + keep = append(keep, sentence(sent)) + } + if len(keep) > 0 { + out = append(out, strings.Join(keep, " ")) + } + } + return strings.Join(out, " ") +} + +// stageTrackerSentences splits text on sentence ends and normalises each +// sentence (trimmed, trailing punctuation dropped, lower-cased first rune) +// for say-it-once comparison. +func stageTrackerSentences(text string) []string { + var out []string + for _, raw := range strings.FieldsFunc(text, func(r rune) bool { return r == '.' || r == '?' || r == '!' }) { + raw = strings.TrimSpace(raw) + if raw == "" { + continue + } + r := []rune(raw) + r[0] = unicode.ToLower(r[0]) + out = append(out, string(r)) + } + return out +} + +// sentence capitalises a clause and ends it with a full stop. +func sentence(s string) string { + s = strings.TrimSpace(s) + if s == "" { + return "" + } + r := []rune(s) + r[0] = unicode.ToUpper(r[0]) + s = string(r) + if !strings.HasSuffix(s, ".") && !strings.HasSuffix(s, "?") && !strings.HasSuffix(s, "!") { + s += "." + } + return s +} + +// decisionDCOBlocker says, before anyone presses Approve, that the head +// cannot merge as-is where DCO is required: the stage record's commit check +// found commits without a Signed-off-by (hivecommons/hive#15136). "" when +// the check is not cached for this head or every commit is signed. +func decisionDCOBlocker(it StageTrackerItem) string { + if it.DCOUnsigned <= 0 { + return "" + } + return fmt.Sprintf("%d of %s no Signed-off-by, so a required DCO check refuses the merge. Re-author as hive PR is the separate choice for that; an Approve never re-authors by itself.", + it.DCOUnsigned, pluralCommitsHave(it.DCOTotal)) +} + +// decisionDCOConsequence is the short DCO caveat under the merge options. +func decisionDCOConsequence(it StageTrackerItem) string { + return fmt.Sprintf("%d of %s no Signed-off-by (DCO)", it.DCOUnsigned, pluralCommitsHave(it.DCOTotal)) +} + +// pluralCommitsHave renders "3 commits have" / "1 commit has" for the DCO +// sentences; a total the record does not know reads "its commits have". +func pluralCommitsHave(total int) string { + switch { + case total == 1: + return "1 commit has" + case total > 1: + return strconv.Itoa(total) + " commits have" + } + return "its commits have" +} + +// decisionReauthorOption is the operator's explicit "re-author as hive PR" +// choice (hivecommons/hive#15136): the hive re-homes the commits on a +// hive-owned, signed-off branch and opens a superseding PR. A person's PR +// is never re-authored by the hive, so for a human author the option is +// shown disabled with the step that does unblock it. +func decisionReauthorOption(it StageTrackerItem, ref string, held bool) StageTrackerDecisionOption { + o := decisionOption(decisionActionReauthor, "Re-author as hive PR", !held && it.AuthorKind != authorKindHuman, "Release the hold first") + if it.AuthorKind == authorKindHuman { + who := "the author" + if it.Author != "" { + who = "@" + it.Author + } + o.ReasonIfDisabled = "Hive does not re-author a person's PR; ask " + who + " to sign off and push" + } + o.Consequence = "Hive reopens " + ref + " as a signed-off hive PR; nothing is merged as-is" + return o +} + +// decisionMergeNowOption is "Merge now as maintainer", or — when the row +// wears needs-rebase, so a plain merge would be a GitHub 405 — "Rebase, +// then merge as maintainer": the same click records the approval, has the +// hive rebase the PR, and merges it on green (hivecommons/hive#14822). +// Either way it is the secondary answer behind "Approve and let hive merge". +func decisionMergeNowOption(it StageTrackerItem, held bool) StageTrackerDecisionOption { + ref := "#" + strconv.Itoa(it.Number) + into := strings.TrimSpace(it.BaseRef) + if into == "" { + into = "its base branch" + } + if stageTrackerNeedsRebase(it) { + opt := decisionOption(decisionActionMergeNow, rebaseMergeFollowThroughLabel, !held, "Release the hold first") + opt.Consequence = rebaseMergeFollowThroughConsequence(it.Number, strings.TrimSpace(it.BaseRef)) + return opt + } + opt := decisionOption(decisionActionMergeNow, decisionMergeNowLabel, !held, "Release the hold first") + opt.Consequence = "Merges " + ref + " into " + into + " now, credited to you" + return opt +} + +// stageTrackerNeedsRebase: the row wears needs-rebase (modifier or label), +// or a rebase-then-merge follow-through is already running on it. +func stageTrackerNeedsRebase(it StageTrackerItem) bool { + if slices.Contains(it.Modifiers, modNeedsRebase) { + return true + } + for _, l := range it.Labels { + if strings.EqualFold(strings.TrimSpace(l), "needs-rebase") { + return true + } + } + return it.RebaseMerge != nil && it.RebaseMerge.State != "" && it.RebaseMerge.State != "merged" && it.RebaseMerge.State != "failed" +} diff --git a/src/pkg/dashboard/stage_tracker_decision_lanes.go b/src/pkg/dashboard/stage_tracker_decision_lanes.go new file mode 100644 index 0000000000..68850309a7 --- /dev/null +++ b/src/pkg/dashboard/stage_tracker_decision_lanes.go @@ -0,0 +1,252 @@ +package dashboard + +import ( + "slices" + "strconv" + "strings" + "time" + + "github.com/hivecommons/hive/pkg/delegatedecision" + stageengineprstage "github.com/hivecommons/hive/pkg/stageengine/prstage" + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// decisionDelegateOption is "Let hive decide" for a state the hive would +// not otherwise decide: the delegate answers in plain words why it won't +// act itself and lists the person's options (hivecommons/hive#15078). +func decisionDelegateOption(held bool, consequence string) StageTrackerDecisionOption { + o := decisionOption(decisionActionDelegate, "Let hive decide", !held, decisionWhyHeld) + o.Consequence = consequence + return o +} + +// decisionForParked is the fallback for any needs-human state without a +// dedicated decision: say what the row is parked on and offer the generic +// moves — look again, hold, flag for a person (hivecommons/hive#15078). +func decisionForParked(it StageTrackerItem, held bool) *StageTrackerDecision { + what := "issue" + if it.Kind == "pr" { + what = "PR" + } + stage := strings.TrimSpace(it.StageLabel) + if stage == "" { + stage = "stage " + strconv.Itoa(it.Stage) + } + d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByLane, BlockerReason: strings.TrimSpace(it.Reason)} + d.Question = "This " + what + " sits at " + stage + ", a stage the hive leaves to a person" + if clause := decisionPlainReason(strings.TrimSpace(it.Reason)); strings.TrimSpace(it.Reason) != "" { + d.Question += " (" + clause + ")" + } + d.Question += ". Act on it on GitHub, then re-evaluate so the hive picks it up." + d.Blocker = "The hive makes no move here until a person does." + if held { + d.Blocker += " " + decisionHeldBlocker(it.Hold) + } + retry := decisionOption(decisionActionRetry, "Re-evaluate now", true, "") + retry.Consequence = "Re-reads GitHub and recomputes the stage" + d.Options = []StageTrackerDecisionOption{retry, decisionDelegateOption(held, "Hive explains what it can do here"), decisionHoldOption(held)} + if !slices.Contains(it.Modifiers, modNeedsHuman) { + d.Options = append(d.Options, decisionOption(decisionActionNeedsHuman, "Mark needs-human", true, "")) + } + return d +} + +// decisionForUnauthorized: a row wearing hive:unauthorized outside 085 — +// the hive's GitHub App lacks the permission for its next step, so a +// person takes that step on GitHub (approve the held workflow runs, merge +// the workflow-file PR, …) and then asks the hive to look again. +func decisionForUnauthorized(it StageTrackerItem, held bool) *StageTrackerDecision { + d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByApp, BlockerReason: strings.TrimSpace(it.Reason)} + step := strings.TrimSpace(it.UnauthorizedStep) + if step == "" { + _, tip := stageTrackerUnauthorized(it.Reason) + d.Question = "The hive's GitHub App lacks a permission for the next step. " + tip + } else { + d.Question = "The hive's GitHub App may not " + unauthorizedStepWords(step) + " here. Do that step on GitHub, then re-evaluate so the hive picks it up." + } + d.Blocker = strings.TrimSpace(it.Unauthorized) + if d.Blocker == "" { + d.Blocker = decisionWhyNoPermission + "." + } + if held { + d.Blocker += " " + decisionHeldBlocker(it.Hold) + } + retry := decisionOption(decisionActionRetry, "Re-evaluate now", true, "") + retry.Consequence = "Re-reads GitHub; hive resumes once the step is done" + d.Options = []StageTrackerDecisionOption{retry, decisionDelegateOption(held, "Hive explains which step it may not take"), decisionHoldOption(held)} + if !slices.Contains(it.Modifiers, modNeedsHuman) { + d.Options = append(d.Options, decisionOption(decisionActionNeedsHuman, "Mark needs-human", true, "")) + } + return d +} + +// decisionForWaitingOnAuthor: a human-authored PR at 071 Needs author / +// 072 Returned to contributor — the hive waits for its author to push. +// The hive never adopts a human's PR, so the person's choices are to wait, +// hold, or close it (hivecommons/hive#15078). +func decisionForWaitingOnAuthor(it StageTrackerItem, held bool) *StageTrackerDecision { + who := "its author" + if a := strings.TrimSpace(it.Author); a != "" { + who = "@" + a + } + ref := "#" + strconv.Itoa(it.Number) + d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByLane, BlockerReason: strings.TrimSpace(it.Reason)} + what := "a new commit" + if clause := decisionPlainReason(strings.TrimSpace(it.Reason)); strings.TrimSpace(it.Reason) != "" && clause != "the hive parked it" { + what = "a new commit (" + clause + ")" + } + d.Question = "This PR waits on " + who + " to push " + what + ". The hive never rewrites a person's PR; it waits unless you say otherwise." + d.Blocker = "Nothing for the hive to do until " + who + " pushes." + if held { + d.Blocker += " " + decisionHeldBlocker(it.Hold) + } + closeSup := decisionOption(decisionActionCloseSuperseded, "Close as superseded", true, "") + closeSup.Consequence = "Closes " + ref + ", naming the PR that replaces it" + closeWontfix := decisionOption(decisionActionCloseWontfix, "Close as won't fix", true, "") + closeWontfix.Consequence = "Closes " + ref + " without merging" + d.Options = []StageTrackerDecisionOption{decisionDelegateOption(held, "Hive weighs waiting against closing; never rewrites the PR"), closeSup, closeWontfix, decisionHoldOption(held)} + return d +} + +// decisionForWaitingOnContributor: a 072 clanker PR whose adoption came due +// and is held (hivecommons/hive#15038). The options are the takeover's. +func decisionForWaitingOnContributor(it StageTrackerItem, held bool, now time.Time) *StageTrackerDecision { + a := it.Adoption + who := "the author" + if a.Author != "" { + who = "@" + a.Author + } + d := &StageTrackerDecision{Since: a.Since, AskedBy: decisionAskedByLane, BlockerReason: "adoption:" + a.BlockerReason()} + gone := "has been offline since the nudge" + if off := strings.TrimSpace(stageTrackerAdoptionOfflineFor(*a, now)); off != "" { + gone = "has been offline for " + off + } + if a.AuthorOnline { + gone = "is online but has not answered " + plural(a.Nudges, "nudge") + } + d.Question = who + " " + gone + " and the hive is not adopting on its own; take the PR over now, or reroute its follow-up work to another clanker?" + d.Blocker = "The PR waits on " + who + "'s hive; adoption is held (" + a.BlockerReason() + ")." + if held { + d.Blocker += " " + decisionHeldBlocker(it.Hold) + } + d.Options = append(takeoverDecisionOptions(it.Takeover, held), decisionHoldOption(held)) + return d +} + +// decisionForAdoption: a nudged 072 PR whose author maintains the +// repository, held for an owner under +// governor.labels.stage.adoption.maintainer_policy: ask +// (hivecommons/hive#14524). The question names the author and how long +// their clanker has been gone; the lead option is Adopt. +func decisionForAdoption(it StageTrackerItem, held bool, now time.Time) *StageTrackerDecision { + a := it.Adoption + who := "the author" + if a.Author != "" { + who = "@" + a.Author + } + d := &StageTrackerDecision{Since: a.Since, AskedBy: decisionAskedByLane, BlockerReason: "adoption:" + a.BlockedBy} + gone := "has been offline since the nudge" + if off := strings.TrimSpace(stageTrackerAdoptionOfflineFor(*a, now)); off != "" { + gone = "has been offline for " + off + } + if a.AuthorOnline { + gone = "is online but has not answered " + plural(a.Nudges, "nudge") + } + d.Question = who + " maintains this repository and " + gone + "; adopt the PR? The hive would take it over as it does any contributor's (the author's commits and sign-off are kept)." + d.Blocker = "maintainer_policy is ask: the hive never adopts a maintainer's PR on its own; a person decides." + if held { + d.Blocker += " " + decisionHeldBlocker(it.Hold) + } + d.Options = []StageTrackerDecisionOption{ + decisionOption(decisionActionAdopt, "Adopt (hive takes over)", !held, "Release the hold first"), + } + d.Options = append(d.Options, takeoverDecisionOptions(it.Takeover, held)...) + d.Options = append(d.Options, decisionHoldOption(held)) + return d +} + +func decisionHoldOption(held bool) StageTrackerDecisionOption { + if held { + return StageTrackerDecisionOption{Action: decisionActionRelease, Label: "Release hold", Enabled: true} + } + return StageTrackerDecisionOption{Action: decisionActionHold, Label: "Hold", Enabled: true} +} + +func decisionOption(action, label string, enabled bool, why string) StageTrackerDecisionOption { + if enabled { + why = "" + } + return StageTrackerDecisionOption{Action: action, Label: label, Enabled: enabled, ReasonIfDisabled: why} +} + +// decisionChangesRequested reports whether the base reason says a swarm +// reviewer asked for changes — directly, or as the lane reason an adoption +// stalled on. +func decisionChangesRequested(base string) bool { + lower := strings.ToLower(strings.TrimSpace(base)) + lower = strings.TrimPrefix(lower, stagelabels.LaneReasonAdoptionStalledPrefix) + switch lower { + case stageengineprstage.ContributorLaneReasonChangesRequested, stagelabels.LaneReasonChangesRequested, + "reviewer-verdict:request_changes", "changes-requested", stageengineprstage.AutoMergeReasonHumanChangesRequested: + return true + } + return false +} + +// decisionLaneRule reports whether the base reason is a lane rule that +// never merges unattended whoever approves (workflow files, removed tests, +// human-merge paths, no reviewer, refused merges, …). +func decisionLaneRule(base string) bool { + lower := strings.ToLower(strings.TrimSpace(base)) + switch lower { + case stageengineprstage.ContributorLaneReasonWorkflowPath, stageengineprstage.ContributorLaneReasonTestsRemoved, + stageengineprstage.ContributorLaneReasonNoReviewer, stageengineprstage.ContributorLaneReasonReporterTrustHold, + stageengineprstage.ContributorLaneReasonNoAppBotLogin, stageengineprstage.ContributorLaneReasonFilesEvidence, + stageengineprstage.AutoMergeReasonHumanMergePath, stageengineprstage.AutoMergeReasonHumanMergePathEvidence, + stageengineprstage.AutoMergeReasonIntentUnauthorized, stageengineprstage.AutoMergeReasonIntentEvidence, + stageengineprstage.AutoMergeReasonMergeRefusedReview, stageengineprstage.AutoMergeReasonMergeRefusedMethod, + stageengineprstage.AutoMergeReasonNoAppBotLogin, stageengineprstage.AutoMergeReasonHumanMergeRequired: + return true + } + return false +} + +// decisionPlainReason renders a lane rule in plain words for the popover +// (the owner's bar: no reason slugs, no stage codes, no hive jargon). +func decisionPlainReason(base string) string { + switch strings.ToLower(strings.TrimSpace(base)) { + case stageengineprstage.ContributorLaneReasonWorkflowPath: + return "it edits CI workflow files" + case stageengineprstage.ContributorLaneReasonTestsRemoved: + return "it removes tests" + case stageengineprstage.ContributorLaneReasonNoReviewer: + return "no reviewer is configured for this repo" + case stageengineprstage.ContributorLaneReasonReporterTrustHold: + return "the hive held it for the trust level of the linked issue's reporter" + case stageengineprstage.ContributorLaneReasonNoAppBotLogin, stageengineprstage.AutoMergeReasonNoAppBotLogin: + return "the hive's GitHub App login is not known" + case stageengineprstage.ContributorLaneReasonFilesEvidence: + return "the hive could not read its changed files" + case stageengineprstage.AutoMergeReasonHumanMergePath, stageengineprstage.AutoMergeReasonHumanMergePathEvidence: + return "it touches files a person must merge" + case stageengineprstage.AutoMergeReasonHumanMergeRequired: + return "it is a breaking change (⚠️ title or needs-owner-merge label) — the owner merges it" + case stageengineprstage.AutoMergeReasonIntentUnauthorized, stageengineprstage.AutoMergeReasonIntentEvidence: + return "the hive could not confirm the author's merge intent" + case stageengineprstage.AutoMergeReasonMergeRefusedReview: + return "GitHub requires a review the hive cannot give" + case stageengineprstage.AutoMergeReasonMergeRefusedMethod: + return "GitHub refused the hive's merge method" + } + // The shared decision glossary (pkg/delegatedecision) covers the + // reasons the lane shares with the delegate — changes requested, + // sentinel, conflicts, red CI, DCO — in the same words the toast and + // the PR comment use (hivecommons/hive#14822). + if e, ok := delegatedecision.Explain(base); ok && e.Kind == delegatedecision.GlossaryReason { + return e.Plain + } + if text := humanizeStageReason(base); text != "" { + return text + } + return "the hive parked it" +} diff --git a/src/pkg/dashboard/stage_tracker_decision_pr.go b/src/pkg/dashboard/stage_tracker_decision_pr.go new file mode 100644 index 0000000000..b0873756de --- /dev/null +++ b/src/pkg/dashboard/stage_tracker_decision_pr.go @@ -0,0 +1,304 @@ +package dashboard + +import ( + "slices" + "strconv" + "strings" + + "github.com/hivecommons/hive/pkg/rebasemerge" + "github.com/hivecommons/hive/pkg/review" + "github.com/hivecommons/hive/pkg/stageengine" + stageengineprstage "github.com/hivecommons/hive/pkg/stageengine/prstage" + "github.com/hivecommons/hive/pkg/stagelabels" +) + +func decisionForPR(it StageTrackerItem, verdict *review.Aggregate, sentinelLabel string, held bool) *StageTrackerDecision { + base, _ := stagelabels.HumanApprovedReason(it.Reason) + base = strings.TrimSpace(base) + lower := strings.ToLower(base) + sha := shortHead(it.Head) + at := "" + if sha != "" { + at = " on " + sha + } + d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByLane, BlockerReason: base} + approveOK, approveWhy := true, "" + delegateOK, delegateWhy := !held, decisionWhyHeld + var selfHold *StageTrackerHold + if held && it.Hold != nil && strings.EqualFold(it.Hold.By, stagelabels.HoldByHive) && it.Hold.Source != "" && it.Hold.Source != stagelabels.HoldSourceLabel { + selfHold = it.Hold + } + + sentinel := it.SentinelAlert || lower == "sentinel" || lower == stageengineprstage.ContributorLaneReasonSentinelBlocked + changes := decisionChangesRequested(base) + laneRule := decisionLaneRule(base) + adoptionLane, adoptionStalled := strings.CutPrefix(base, stagelabels.LaneReasonAdoptionStalledPrefix) + forkGuard, forkGuarded := strings.CutPrefix(base, stageengineprstage.StageReasonForkGuard) + // hivecommons/hive#15307: the hive's adoption copy (or the original it + // supersedes) after the fixer's two rebase-resolve attempts failed. + rebaseFailedTwice := lower == stagelabels.LaneReasonRebaseFailedTwice || (adoptionStalled && adoptionLane == stagelabels.LaneReasonRebaseFailedTwice) + reviewerDeferred := lower == stageengine.StageReasonVerdictRequiresHuman || lower == stageengine.StageReasonDecisionRequested + + // WHAT it is waiting on: the question, most specific source first. A + // reviewer's own question is quoted verbatim — it is the text the + // hive's "Needs a decision" comment on the PR prints after "reviewer + // question:", read from the same verdict record. + switch { + case it.UnauthorizedStep != "": + d.AskedBy = decisionAskedByApp + d.Question = "The hive's GitHub App may not " + unauthorizedStepWords(it.UnauthorizedStep) + " here. A maintainer has to do that step on GitHub." + d.Blocker = strings.TrimSpace(it.Unauthorized) + delegateOK, delegateWhy = false, decisionWhyNoPermission + approveOK, approveWhy = false, decisionWhyApproveNoGrant + case verdict != nil && strings.TrimSpace(verdict.DecisionQuestion) != "": + d.AskedBy = decisionAskedByReviewer + d.Question = strings.TrimSpace(verdict.DecisionQuestion) + if !verdict.RecordedAt.IsZero() { + t := verdict.RecordedAt + d.Since = &t + } + case verdict != nil && verdict.RedundantOf > 0: + d.AskedBy = decisionAskedByReviewer + d.Question = "A reviewer found this PR's change already on the base through #" + strconv.Itoa(verdict.RedundantOf) + ". Close it as superseded, or give direction?" + if !verdict.RecordedAt.IsZero() { + t := verdict.RecordedAt + d.Since = &t + } + case selfHold != nil: + // The hive held the PR itself (hivecommons/hive#15020): say so, + // name the gate and the issue, and offer release / keep. + d.AskedBy = decisionAskedByLane + d.Question = "The hive held this PR itself for " + decisionHoldReason(selfHold) + ". Release the hold (the lane then merges it on its next pass once the other gates are clear), or keep it?" + if selfHold.Since != nil { + t := *selfHold.Since + d.Since = &t + } + d.Blocker = "The hive set `hold` on its own: " + decisionHoldReason(selfHold) + ". It does nothing more until the hold is released." + d.BlockerReason = decisionBlockerHoldHive + case verdict != nil && decisionFirstNonEmpty(verdict.HumanSummaries) != "": + d.AskedBy = decisionAskedByReviewer + d.Question = "A reviewer handed this to a person: " + decisionFirstNonEmpty(verdict.HumanSummaries) + if !verdict.RecordedAt.IsZero() { + t := verdict.RecordedAt + d.Since = &t + } + case reviewerDeferred: + d.AskedBy = decisionAskedByReviewer + d.Question = "A reviewer handed this PR to a person without a specific question. Merge it as is, give direction, or close it?" + case sentinel: + d.AskedBy = decisionAskedBySentinel + reason := strings.TrimSpace(it.SentinelReason) + if reason == "" { + reason = "security-relevant changes" + } + d.Question = "The security check flagged " + reason + at + ". Accept it as is, give direction, or close it?" + case lower == stagelabels.LaneReasonAdoptionChildClosedTwice: + d.Question = "The hive's copies of this PR were closed without merging twice within an hour, so the hive stopped opening copies. Reopen the last copy (#" + strconv.Itoa(it.AdoptedBy) + "), give direction, or close it?" + case rebaseFailedTwice: + d.Question = "The hive adopted this PR but its fixer could not resolve the conflicts with the base in two attempts. Adopt the commits into a fresh branch, give direction, or close it as superseded?" + case lower == stagelabels.LaneReasonAdoptionCopyFailed: + d.Question = "The hive's copy of this PR (#" + strconv.Itoa(it.AdoptedBy) + ") failed, so this PR was reopened. Ask the hive to supersede it again, give direction, or close it?" + case adoptionStalled: + d.Question = "The hive took this PR over but could not move it (" + decisionPlainReason(adoptionLane) + "). Give direction, or close it?" + case forkGuarded: + d.Question = "CI will not run for this fork PR (" + strings.ReplaceAll(forkGuard, ",", ", ") + "). A maintainer must push the branch to this repo — or close it?" + case changes: + d.AskedBy = decisionAskedByReviewer + d.Question = "A reviewer requested changes" + at + ". Give direction for a new commit, or close it?" + case laneRule: + d.Question = "The hive never merges this by itself (" + decisionPlainReason(base) + "). Approve it for a maintainer to merge, give direction, or close it?" + default: + clause := decisionPlainReason(base) + if base == "" { + clause = strings.TrimSpace(it.Caption) + } + if clause == "" { + clause = "the hive parked it" + } + d.Question = "A person must decide (" + clause + "). Approve, give direction, or close?" + } + + // The blocker in plain words, and what it disables. + switch { + case it.UnauthorizedStep != "": + // set above + case changes: + d.Blocker = "A reviewer requested changes" + at + " — needs a new commit. Approving cannot override that." + approveOK, approveWhy = false, d.Blocker + case sentinel: + d.Blocker = "The security check has an open alert. The hive will not merge until a person removes the `" + sentinelLabel + "` label." + if base == "" { + d.BlockerReason = decisionBlockerSentinel + } + case laneRule: + d.Blocker = "The hive never merges this by itself. After approval, a maintainer merges." + case forkGuarded: + d.Blocker = "Neither the author nor the hive can make CI run for this fork PR." + case reviewerDeferred: + d.Blocker = "The hive will not merge until a person decides." + if verdict != nil && strings.TrimSpace(verdict.DecisionFinding) != "" { + d.Blocker = "The review found: " + strings.TrimSpace(verdict.DecisionFinding) + ". " + d.Blocker + } + } + if held && selfHold == nil { + if d.Blocker != "" { + d.Blocker += " " + } + d.Blocker += decisionHeldBlocker(it.Hold) + if d.BlockerReason == "" { + d.BlockerReason = decisionBlockerHold + } + } + + d.Options = []StageTrackerDecisionOption{ + decisionOption(decisionActionDelegate, "Let hive decide", delegateOK, delegateWhy), + decisionOption(decisionActionApprove, "Approve", approveOK, approveWhy), + decisionOption(decisionActionDirection, "Give direction", true, ""), + decisionOption(decisionActionCloseSuperseded, "Close as superseded", true, ""), + decisionOption(decisionActionCloseWontfix, "Close as won't fix", true, ""), + decisionHoldOption(held), + } + // A PR parked here that also needs a rebase has no lane rebasing it + // until a person speaks (hivecommons/hive#14822): offer the maintainer + // merge with the rebase folded in, right after Approve. + if stageTrackerNeedsRebase(it) && !sentinel { + d.Options = slices.Insert(d.Options, 2, decisionMergeNowOption(it, held)) + } + if rebaseFailedTwice { + // The two answers to a rebase nobody could finish lead, as they do + // for merge-now (rebaseMergeFailureOptions). + d.Options = slices.Insert(d.Options, 0, decisionOption(decisionActionAdopt, rebasemerge.OptionAdoptFreshLabel, true, "")) + } + if selfHold != nil { + // Release leads: it is the one action that answers the question. + d.Options = append([]StageTrackerDecisionOption{decisionHoldOption(true)}, d.Options[:len(d.Options)-1]...) + } + if verdict != nil && verdict.RedundantOf > 0 && selfHold == nil { + // The reviewer named the PR that already carries this change + // (hivecommons/hive#15499): closing as superseded is the answer + // to that question, so it leads and says which PR. + d.RedundantOf = verdict.RedundantOf + d.Options = decisionLeadWithCloseSuperseded(d.Options, verdict.RedundantOf) + } + return d +} + +// decisionLeadWithCloseSuperseded moves "Close as superseded" to the front +// of opts with the superseding PR named in its consequence. +func decisionLeadWithCloseSuperseded(opts []StageTrackerDecisionOption, redundantOf int) []StageTrackerDecisionOption { + lead := decisionOption(decisionActionCloseSuperseded, "Close as superseded", true, "") + lead.Consequence = "Closes this PR as superseded by #" + strconv.Itoa(redundantOf) + ", which already carries its change." + lead.Lead = true + out := make([]StageTrackerDecisionOption, 0, len(opts)+1) + out = append(out, lead) + for _, o := range opts { + if o.Action == decisionActionCloseSuperseded { + continue + } + out = append(out, o) + } + return out +} + +// decisionHoldReason is the hold's plain-words reason for the popover. +func decisionHoldReason(h *StageTrackerHold) string { + if h != nil { + if reason := strings.TrimSpace(h.Reason); reason != "" { + return reason + } + } + return "its own gate" +} + +// decisionHeldBlocker is the "On hold" blocker sentence, naming who set the +// hold when the row knows (hivecommons/hive#15020). +func decisionHeldBlocker(h *StageTrackerHold) string { + if h == nil || strings.TrimSpace(h.By) == "" { + return decisionHeldBlockerPlain + } + who := "@" + strings.TrimSpace(h.By) + if strings.EqualFold(h.By, stagelabels.HoldByHive) { + who = "the hive" + } + s := "On hold (set by " + who + if reason := strings.TrimSpace(h.Reason); reason != "" { + s += ": " + reason + } + return s + ") — the hive does nothing until the hold is released." +} + +func decisionForIssue(it StageTrackerItem, held bool) *StageTrackerDecision { + d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByHiveAgent, BlockerReason: strings.TrimSpace(it.Reason)} + d.Question = "The hive parked this issue for a person. Approve the direction, send it back with direction, or close it?" + d.Blocker = "No agent picks this up until a person answers. The hive's question is in its latest comment on the issue." + if held { + d.Blocker += " " + decisionHeldBlocker(it.Hold) + if d.BlockerReason == "" { + d.BlockerReason = decisionBlockerHold + } + } + d.Options = []StageTrackerDecisionOption{ + decisionOption(decisionActionDelegate, "Let hive decide", !held, decisionWhyHeld), + decisionOption(decisionActionApprove, "Approve direction", true, ""), + decisionOption(decisionActionDirection, "Send back", true, ""), + decisionOption(decisionActionCloseSuperseded, "Close as superseded", true, ""), + decisionOption(decisionActionCloseWontfix, "Close as won't fix", true, ""), + decisionHoldOption(held), + } + return d +} + +func decisionForTriage(it StageTrackerItem, held bool) *StageTrackerDecision { + d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByTriage, BlockerReason: strings.TrimSpace(it.Reason)} + d.Question = "Should the hive work on this issue? Accept triage so an agent can take it, hold it, or mark it needs-human." + d.Blocker = "No agent picks up an issue until a maintainer accepts triage." + if held { + d.Blocker += " " + decisionHeldBlocker(it.Hold) + } + d.Options = []StageTrackerDecisionOption{ + decisionOption(decisionActionAcceptTriage, "Accept triage", true, ""), + decisionDelegateOption(held, "Hive triages it for you, or explains why not"), + decisionHoldOption(held), + } + if !slices.Contains(it.Modifiers, modNeedsHuman) { + d.Options = append(d.Options, decisionOption(decisionActionNeedsHuman, "Mark needs-human", true, "")) + } + return d +} + +func decisionForNeedsHuman(it StageTrackerItem, held bool) *StageTrackerDecision { + d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByEscalation, BlockerReason: "label:" + modNeedsHuman} + what := "issue" + if it.Kind == "pr" { + what = "PR" + } + d.Question = "This " + what + " is marked needs-human: automated fixes ran out, or a person flagged it. Review it, then resolve it here (lifts the label) or remove the label on GitHub when the hive may continue." + d.Blocker = "The hive does nothing with a needs-human item until a person removes the label." + if held { + d.Blocker += " " + decisionHeldBlocker(it.Hold) + } + // The matching action for the ask (hivecommons/hive#15078): Approve + // lifts needs-human — on a PR it also posts /lgtm + /approve as the + // operator, on an issue it records /hive approve and un-parks it. + resolve := decisionOption(decisionActionApprove, "Resolve — lift needs-human", !held, "Release the hold first") + if it.Kind == "pr" { + resolve.Consequence = "Lifts needs-human and approves as you; hive merges" + } else { + resolve.Consequence = "Lifts needs-human and approves as you; hive carries on" + } + d.Options = []StageTrackerDecisionOption{resolve} + // A needs-human PR still waiting on its contributor's clanker offers + // the takeover actions too (hivecommons/hive#15038). + d.Options = append(d.Options, takeoverDecisionOptions(it.Takeover, held)...) + d.Options = append(d.Options, decisionDelegateOption(held, "Hive reviews it and lifts needs-human, or explains why not"), decisionHoldOption(held)) + return d +} + +func decisionFirstNonEmpty(ss []string) string { + for _, s := range ss { + if t := strings.TrimSpace(s); t != "" { + return t + } + } + return "" +} diff --git a/src/pkg/dashboard/stage_tracker_merge_train.go b/src/pkg/dashboard/stage_tracker_merge_train.go index 8a82dd09be..140402ab4a 100644 --- a/src/pkg/dashboard/stage_tracker_merge_train.go +++ b/src/pkg/dashboard/stage_tracker_merge_train.go @@ -1,13 +1,8 @@ package dashboard import ( - "log/slog" - "reflect" "slices" - "sort" "strconv" - "strings" - "sync" "time" "github.com/hivecommons/hive/pkg/config" @@ -235,713 +230,3 @@ type StageTrackerLeftTrain struct { trainID string position int } - -// StageTrackerOverlap is the hint on a PR short of the merge queue whose -// files overlap another open PR's: Behind is the PR it will queue behind -// once both are merge-ready (0 when this one is the planner's front), -// With the other overlapping PRs, Files the overlapping files and Note -// the one line the row shows — "overlaps #15637 (sidebar.html, -// index.html) — will queue behind it". The row has no merge_train, no -// ordinal and no rail: the train starts at 080. -type StageTrackerOverlap struct { - Behind int `json:"behind,omitempty"` - With []int `json:"with,omitempty"` - Files []string `json:"files,omitempty"` - Note string `json:"note"` - // trainID and position remember the planner's slot so the members - // that do ride can close ranks (stageTrackerMergeTrainPostPass). - trainID string - position int -} - -// stageTrackerOverlapHint builds the hint for a PR at number, out of a -// train whose planner's front is front and whose other members are -// others (number excluded by the caller). -func stageTrackerOverlapHint(number, front int, others []int, files []string) *StageTrackerOverlap { - o := &StageTrackerOverlap{With: append([]int(nil), others...), Files: append([]string(nil), files...)} - paren := "" - if len(files) > 0 { - paren = " (" + strings.Join(files, ", ") + ")" - } - if number != front && front > 0 { - o.Behind = front - o.Note = "overlaps #" + strconv.Itoa(front) + paren + " — will queue behind it" - return o - } - names := make([]string, 0, len(others)) - for _, n := range others { - names = append(names, "#"+strconv.Itoa(n)) - } - them := "it" - if len(others) > 1 { - them = "them" - } - o.Note = "overlaps " + strings.Join(names, ", ") + paren + " — merges ahead of " + them + " once both are ready" - if len(others) > 1 { - o.Note = strings.Replace(o.Note, "once both are ready", "once all are ready", 1) - } - return o -} - -// stageTrackerLeaveMergeTrainBelowQueue takes a PR short of the merge -// queue out of its train and leaves the overlap hint in its place. -func stageTrackerLeaveMergeTrainBelowQueue(it *StageTrackerItem, front int, others []int) { - if it == nil || it.MergeTrain == nil { - return - } - mt := it.MergeTrain - pos := mt.Position - if mt.State == MergeGateStateTrainFront { - pos = 1 - } - stageTrackerLeaveMergeTrain(it, "") - it.Overlap = stageTrackerOverlapHint(it.Number, front, others, mt.OverlapFiles) - it.Overlap.trainID, it.Overlap.position = mt.ID, pos -} - -// stageTrackerTrainUnderRepair names why a PR at stage, with reason, is -// not a train member right now — "" when it may ride. A PR being fixed -// (070), waiting on its author (071) or contributor (072), freshly -// adopted (074), parked on a human decision (085), or whose required -// checks are red is somebody's to repair first; the planner may still -// have ordered it, but the view never seats it. A PR short of the merge -// queue is not under repair but rides no train either -// (stageTrackerBelowMergeQueue). -// -// stageTrackerItemColumn reads the same predicate for the chevron -// column, and stageTrackerUnderRepair in the SPA mirrors it: membership -// and column can never disagree (hive's own #15574 sat at 070 "Fixing" -// under Merge queue because its stale merge-failed gate still promoted -// the column after the train rule had already dropped it). -func stageTrackerTrainUnderRepair(stage int, reason string) string { - switch stage { - case stagelabels.Fixing.Number(): - return stagelabels.Fixing.Slug() - case stagelabels.NeedsAuthor.Number(): - return stagelabels.NeedsAuthor.Slug() - case stagelabels.ReturnedToContributor.Number(): - return stagelabels.ReturnedToContributor.Slug() - case stagelabels.AdoptedByHive.Number(): - return stagelabels.AdoptedByHive.Slug() - case stagelabels.NeedsDecision.Number(): - return stagelabels.NeedsDecision.Slug() - } - lower := strings.ToLower(strings.TrimSpace(reason)) - if strings.HasPrefix(lower, "required-check-failing:") || strings.HasPrefix(lower, "check-failing:") || lower == "ci-red" { - return "checks-failing" - } - return "" -} - -// stageTrackerLeaveMergeTrain takes a PR out of its train: the train -// record and the train's gate words go, and LeftTrain keeps why (and, -// unexported, which train and which slot) so the row can say so on hover -// and the survivors can close ranks. why "" (a train that shrank to one -// member) leaves no note — there is no train to have left. -func stageTrackerLeaveMergeTrain(it *StageTrackerItem, why string) { - if it == nil || it.MergeTrain == nil { - return - } - mt := it.MergeTrain - if it.MergeGate != nil && (it.MergeGate.State == mt.State || it.MergeGate.State == MergeGateStateTrainFront) { - // Back to the stage's own gate state (ready at 080, pending at - // 060); off the gate there is no gate. - it.MergeGate.State = "" - switch it.Stage { - case stagelabels.Reviewed.Number(): - it.MergeGate.State = MergeGateStatePending - case stagelabels.AwaitingMergeAdmission.Number(): - it.MergeGate.State = MergeGateStateReady - } - it.MergeGate.Reason = "" - if it.MergeGate.State == "" || reflect.DeepEqual(*it.MergeGate, StageTrackerMergeGate{}) { - it.MergeGate = nil - } - } - it.MergeTrain = nil - // The caption the train wrote ("waiting its turn … behind #N") is - // stale now; an 080 row goes back to the gate's own words. - if it.Stage == stagelabels.AwaitingMergeAdmission.Number() && (it.Caption == stageTrackerMergeTrainCaption(it.Reason) || it.Caption == stageTrackerMergeTrainFrontCaption(mt)) { - it.Caption = stageTrackerAwaitingAdmissionCaption - } - if why != "" { - pos := mt.Position - if mt.State == MergeGateStateTrainFront { - pos = 1 - } - it.LeftTrain = &StageTrackerLeftTrain{Why: why, Note: stageTrackerLeftTrainNote, trainID: mt.ID, position: pos} - } -} - -// stageTrackerMergeTrainFrontGate words the gate of the member merging -// first: "1st in the merge queue; merges next (1st of 2, overlapping -// files: a.go)". promoted is a member that was queued behind a front -// that just left: its queued words are stale and are replaced. -func stageTrackerMergeTrainFrontGate(front *StageTrackerItem, size int, files []string, promoted bool) { - if front.MergeGate == nil { - front.MergeGate = &StageTrackerMergeGate{} - } - if front.MergeGate.State == "" || front.MergeGate.State == MergeGateStateReady || (promoted && front.MergeGate.State == MergeGateStateQueuedBehind) { - front.MergeGate.State = MergeGateStateTrainFront - } - if front.MergeGate.Reason == "" || promoted { - front.MergeGate.Reason = "1st in the merge queue; merges next (1st of " + strconv.Itoa(size) + ", overlapping files: " + strings.Join(files, ", ") + ")" - } -} - -// stageTrackerMergeTrainPostPass runs over the finished items: the front -// (which the lane evaluates on its normal path and so carries no train -// reason) is marked from its siblings' records, and every member learns -// the PRs ahead of it. Members are matched on repo and base. A member -// under repair (stageTrackerTrainUnderRepair) leaves the train first — -// the front included — as does one short of the merge queue -// (stageTrackerBelowMergeQueue, which keeps an overlap hint instead); -// the rest close ranks (size, place, front and ahead recomputed), and a -// train left with one member is no train at all: no header, no ordinal -// (hivecommons/hive#15405 led a header as "1st: #15405" while its own -// chevron read "Fixing"; hive's own #15637/#15633 led one while both -// read CI / Review). -func stageTrackerMergeTrainPostPass(items []StageTrackerItem, opts mergeTrainQueueOptions, mem *mergeTrainMemory) { - type trainKey struct{ repo, id string } - // Every row the planner ordered, by train, before the view decides who - // rides; the overlap hint on a row that does not names the rest. - ordered := map[trainKey][]int{} - samples := map[trainKey]*StageTrackerMergeTrain{} - var keys []trainKey - for i := range items { - it := &items[i] - if it.MergeTrain == nil || it.Kind != "pr" { - continue - } - k := trainKey{it.Repo, it.MergeTrain.ID} - if _, seen := samples[k]; !seen { - samples[k] = it.MergeTrain - keys = append(keys, k) - } - ordered[k] = append(ordered[k], i) - } - for _, key := range keys { - sample := *samples[key] - frontIdx := -1 - for i := range items { - it := &items[i] - if it.Kind == "pr" && it.Repo == key.repo && it.Number == sample.Front && it.Stage < stageTrackerMergedStage { - frontIdx = i - break - } - } - roster := func(except int) []int { - var out []int - if frontIdx >= 0 && items[frontIdx].Number != except { - out = append(out, items[frontIdx].Number) - } - for _, i := range ordered[key] { - if items[i].Number != except { - out = append(out, items[i].Number) - } - } - sort.Ints(out) - return out - } - var idx []int - for _, i := range ordered[key] { - it := &items[i] - // A rebase-exhausted tail sits at 085 by the train's own doing; - // it stays so the person who rebases it sees where it merges. - if it.MergeTrain.State != MergeGateStateRebaseExhausted { - if why := stageTrackerTrainUnderRepair(it.Stage, it.Reason); why != "" { - stageTrackerLeaveMergeTrain(it, why) - continue - } - if stageTrackerBelowMergeQueue(it.Stage) { - stageTrackerLeaveMergeTrainBelowQueue(it, sample.Front, roster(it.Number)) - continue - } - } - idx = append(idx, i) - } - frontLeft := false - if frontIdx >= 0 && items[frontIdx].MergeTrain == nil { - front := &items[frontIdx] - if why := stageTrackerTrainUnderRepair(front.Stage, front.Reason); why != "" { - front.LeftTrain = &StageTrackerLeftTrain{Why: why, Note: stageTrackerLeftTrainNote, trainID: sample.ID, position: 1} - frontLeft = true - } else if stageTrackerBelowMergeQueue(front.Stage) { - front.Overlap = stageTrackerOverlapHint(front.Number, sample.Front, roster(front.Number), sample.OverlapFiles) - front.Overlap.trainID, front.Overlap.position = sample.ID, 1 - frontLeft = true - } else { - front.MergeTrain = &StageTrackerMergeTrain{ - ID: sample.ID, State: MergeGateStateTrainFront, Front: sample.Front, Position: 1, Size: sample.Size, - OverlapFiles: append([]string(nil), sample.OverlapFiles...), - } - stageTrackerMergeTrainFrontGate(front, sample.Size, sample.OverlapFiles, false) - if front.Stage == stagelabels.AwaitingMergeAdmission.Number() { - front.Caption = stageTrackerMergeTrainFrontCaption(&sample) - } - idx = append(idx, frontIdx) - } - } - if len(idx) == 0 { - continue - } - // The queue is the members that ride in this payload — never the - // planner's count, which includes PRs the view does not seat - // (below 080, under repair, a record another lane overwrote): - // hive's own header read "2 of 9 PRs here · not in this view: 7 - // more" over the only two PRs actually queued (hivecommons/hive#15653). - // Members the view sent elsewhere; one survivor is no train. - var dropped []int - for i := range items { - it := &items[i] - if it.Kind != "pr" || it.Repo != key.repo || it.MergeTrain != nil { - continue - } - if it.LeftTrain != nil && it.LeftTrain.trainID == sample.ID { - dropped = append(dropped, it.LeftTrain.position) - } else if it.Overlap != nil && it.Overlap.trainID == sample.ID { - dropped = append(dropped, it.Overlap.position) - } - } - if len(dropped) > 0 { - if sample.Size-len(dropped) < 2 { - for _, i := range idx { - stageTrackerLeaveMergeTrain(&items[i], "") - } - continue - } - } - // Riders keep their planner order but take slots 1..N: a member - // the planner seated 5th of 9 whose seven neighbours never rode - // (below the merge queue, under repair, or not in this payload) - // is 2nd of 2 here, never "5th of 2". - sort.Slice(idx, func(a, b int) bool { - return items[idx[a]].MergeTrain.Position < items[idx[b]].MergeTrain.Position - }) - for n, i := range idx { - items[i].MergeTrain.Position = n + 1 - } - for _, i := range idx { - mt := items[i].MergeTrain - mt.Size = len(idx) - // The front's gate and caption counted the planner's size; - // say the size of the train that rides. - if mt.State == MergeGateStateTrainFront && mt.Size != sample.Size { - front := &items[i] - stageTrackerMergeTrainFrontGate(front, mt.Size, mt.OverlapFiles, true) - if front.Stage == stagelabels.AwaitingMergeAdmission.Number() && front.Caption == stageTrackerMergeTrainFrontCaption(&sample) { - front.Caption = stageTrackerMergeTrainFrontCaption(mt) - } - } - } - // Members in merge order, so each one's Ahead is the prefix. - if frontLeft { - // The old front is out; the member now in slot 1 leads. - newFront := 0 - if first := &items[idx[0]]; first.MergeTrain.Position == 1 { - newFront = first.Number - first.MergeTrain.State = MergeGateStateTrainFront - stageTrackerMergeTrainFrontGate(first, first.MergeTrain.Size, first.MergeTrain.OverlapFiles, true) - frontIdx = idx[0] - } - for _, i := range idx { - items[i].MergeTrain.Front = newFront - } - } - members := make([]int, 0, len(idx)) - for _, i := range idx { - members = append(members, items[i].Number) - } - for n, i := range idx { - var ahead []int - for _, j := range idx[:n] { - ahead = append(ahead, items[j].Number) - } - items[i].MergeTrain.Ahead = ahead - items[i].MergeTrain.Members = append([]int(nil), members...) - } - var head *StageTrackerItem - if frontIdx >= 0 { - head = &items[frontIdx] - } - for n, i := range idx { - ahead := make([]*StageTrackerItem, 0, n) - for _, j := range idx[:n] { - ahead = append(ahead, &items[j]) - } - stageTrackerMergeTrainQueueFacts(&items[i], ahead, head, opts, mem) - } - } -} - -// stageTrackerMergeTrainQueueFacts fills the chip's queue facts on one -// member: what the head is doing, how long it has sat there, the estimate -// of this member's own turn and whether the train reads stalled. ahead is -// every member before this one in merge order (the head first, when it is -// in the view); mem remembers each member's first estimate so a turn that -// has overrun it twice over reads "running late". -func stageTrackerMergeTrainQueueFacts(self *StageTrackerItem, ahead []*StageTrackerItem, head *StageTrackerItem, opts mergeTrainQueueOptions, mem *mergeTrainMemory) { - if self == nil || self.MergeTrain == nil { - return - } - mt := self.MergeTrain - mt.Length = mt.Size - mt.HeadNumber = mt.Front - state, reason, headLeft, known := mergeTrainHeadState(head, opts.Now) - mt.HeadState, mt.HeadReason = state, reason - if head != nil && head.StageSince != nil && !head.StageSince.IsZero() { - since := *head.StageSince - mt.HeadSince = &since - } - mt.EtaS, mt.EtaAt, mt.EtaBasis, mt.Late = 0, nil, "", false - // Stalled: the head has sat in its stage past the warn window and is - // not actually merging. A soaking head is on its clock, not stalled, - // until that clock has itself overrun the window. - if opts.StallWarn > 0 && mt.HeadSince != nil && state != mergeTrainHeadMerging && state != mergeTrainHeadUnknown { - sat := opts.Now.Sub(*mt.HeadSince) - if sat > opts.StallWarn && !(state == mergeTrainHeadSoaking && headLeft > 0) { - mt.Stalled = true - mt.StalledS = int64(sat / time.Second) - } - } - // No estimate while the head (or this member) waits on a person or on - // CI: the blocker is the word, not a clock. - if !known || self.NeedsHuman || self.Hold != nil { - if mem != nil { - mem.forgetEta(self) - } - return - } - // The estimate (hivecommons/hive#15395): this member's own soak left, - // plus each PR ahead — its remaining soak, or one sweep when it has - // none — plus the wait for the next sweep tick. - sweep := opts.Sweep - if sweep <= 0 { - sweep = mergeTrainDefaultSweepEvery - } - var eta time.Duration - own := stageTrackerSoakLeftOf(self, opts.Now) - eta += own - for i, a := range ahead { - left := stageTrackerSoakLeftOf(a, opts.Now) - if i == 0 && a == head { - left = headLeft - } - if left <= 0 { - left = sweep - } - eta += left - } - tick := opts.NextSweepIn(self) - eta += tick - if eta < time.Second { - eta = time.Second - } - mt.EtaS = int64(eta / time.Second) - at := opts.Now.Add(eta) - mt.EtaBasis = mergeTrainEtaBasis(len(ahead), state, headLeft, own, tick, self.MergeGate != nil && self.MergeGate.SweepRunning) - if mem != nil { - at, mt.Late = mem.etaAnchor(self, mt, at, opts.Now, sweep) - } - mt.EtaAt = &at -} - -// mergeTrainDefaultSweepEvery stands in for the lanes' floor cadence -// before the sweep loop has armed it (automerge's floor interval). -const mergeTrainDefaultSweepEvery = 5 * time.Minute - -// NextSweepIn is how long until the next sweep tick: the member's own -// next_sweep_at when the gate carries one, else the lanes' floor; 0 while -// a sweep runs or none is armed. -func (o mergeTrainQueueOptions) NextSweepIn(self *StageTrackerItem) time.Duration { - if self != nil && self.MergeGate != nil { - if self.MergeGate.SweepRunning { - return 0 - } - if self.MergeGate.NextSweepAt != nil && self.MergeGate.NextSweepAt.After(o.Now) { - return self.MergeGate.NextSweepAt.Sub(o.Now) - } - } - if !o.NextSweepAt.IsZero() && o.NextSweepAt.After(o.Now) { - return o.NextSweepAt.Sub(o.Now) - } - return 0 -} - -// stageTrackerSoakLeftOf is how much of an item's own soak clock remains. -func stageTrackerSoakLeftOf(it *StageTrackerItem, now time.Time) time.Duration { - if it == nil { - return 0 - } - if it.MergeGate != nil && it.MergeGate.SoakRemainingSeconds > 0 { - return time.Duration(it.MergeGate.SoakRemainingSeconds) * time.Second - } - if it.Soak != nil && it.Soak.Until.After(now) { - return it.Soak.Until.Sub(now) - } - return 0 -} - -// mergeTrainEtaBasis is the short plain-English reading of the estimate: -// "2 ahead · head soaking 12m · next pass in 40s". -func mergeTrainEtaBasis(aheadN int, headState string, headLeft, own, tick time.Duration, sweeping bool) string { - var parts []string - switch aheadN { - case 0: - parts = append(parts, "1st in queue") - case 1: - parts = append(parts, "1 ahead") - default: - parts = append(parts, strconv.Itoa(aheadN)+" ahead") - } - if aheadN > 0 && headState == mergeTrainHeadSoaking && headLeft > 0 { - parts = append(parts, "head soaking "+shortDuration(headLeft)) - } else if aheadN > 0 && headState == mergeTrainHeadMerging { - parts = append(parts, "head merging") - } - if own > 0 { - parts = append(parts, "own soak "+shortDuration(own)) - } - if sweeping { - parts = append(parts, "pass running") - } else if tick > 0 { - parts = append(parts, "next pass in "+shortDuration(tick)) - } - return strings.Join(parts, " · ") -} - -// mergeTrainHeadState reads the head's current state, its plain-word -// reason, how long its own clock still runs (soak left, next sweep) and -// whether that clock is known at all (false on a person or CI). -func mergeTrainHeadState(head *StageTrackerItem, now time.Time) (state, reason string, remaining time.Duration, known bool) { - if head == nil { - return mergeTrainHeadUnknown, "the head of the train is not in this view", 0, false - } - mg := head.MergeGate - if mg != nil && mg.State == MergeGateStateMerging { - return mergeTrainHeadMerging, "merging now", 0, true - } - if mg != nil && mg.State == MergeGateStateMergeFailed { - return mergeTrainHeadReady, "GitHub refused the last merge; hive retries on its next pass", 0, false - } - switch head.Stage { - case trackerNumberReadyForHuman: - why := "waiting for a maintainer" - if head.HumanMergeReason != "" { - why += " (" + strings.ReplaceAll(head.HumanMergeReason, "-", " ") + ")" - } - return mergeTrainHeadNeedsHuman, why, 0, false - case trackerNumberNeedsDecision, trackerNumberIssueDecision: - return mergeTrainHeadNeedsHuman, "waiting for a human decision", 0, false - case stagelabels.MergeQueue.Number(): - return mergeTrainHeadMerging, "merging now", 0, true - case trackerNumberPreMergeSoak: - left := time.Duration(0) - if mg != nil && mg.SoakRemainingSeconds > 0 { - left = time.Duration(mg.SoakRemainingSeconds) * time.Second - } - if left <= 0 && head.Soak != nil && head.Soak.Until.After(now) { - left = head.Soak.Until.Sub(now) - } - if left > 0 { - return mergeTrainHeadSoaking, "soaking, " + shortDuration(left) + " left", left, true - } - return mergeTrainHeadSoaking, "soaked; hive merges it on its next pass", 0, true - case trackerNumberReviewed, trackerNumberReviewPending: - return mergeTrainHeadCI, "waiting for CI", 0, false - case trackerNumberFixing, trackerNumberReturned, trackerNumberNeedsAuthor: - return mergeTrainHeadFixing, "being fixed by its author", 0, false - } - if head.Hold != nil || head.NeedsHuman { - return mergeTrainHeadNeedsHuman, "waiting for a maintainer", 0, false - } - if head.Soak != nil && head.Soak.Until.After(now) { - left := head.Soak.Until.Sub(now) - return mergeTrainHeadSoaking, "soaking, " + shortDuration(left) + " left", left, true - } - var next time.Duration - if mg != nil && mg.NextSweepAt != nil && mg.NextSweepAt.After(now) { - next = mg.NextSweepAt.Sub(now) - } - return mergeTrainHeadReady, "approved and green; merges on hive's next pass", next, true -} - -// shortDuration is "12m" / "1h 05m" / "45s" for the chip's words. -func shortDuration(d time.Duration) string { - d = d.Round(time.Second) - if d < time.Minute { - return strconv.Itoa(int(d/time.Second)) + "s" - } - m := int(d / time.Minute) - if m < 60 { - return strconv.Itoa(m) + "m" - } - rem := m % 60 - if rem == 0 { - return strconv.Itoa(m/60) + "h" - } - rest := strconv.Itoa(rem) - if rem < 10 { - rest = "0" + rest - } - return strconv.Itoa(m/60) + "h " + rest + "m" -} - -// mergeTrainMemory is what the tracker keeps between builds for the -// trains: the hour-stamp of each stalled train's activity-log line and -// each member's first estimate (for "running late"). -type mergeTrainMemory struct { - mu sync.Mutex - last map[string]time.Time - eta map[string]mergeTrainEtaMark -} - -// mergeTrainEtaMark is a member's first estimate at a given position. -type mergeTrainEtaMark struct { - At time.Time - Eta time.Duration - Position int -} - -const mergeTrainStallLogEvery = time.Hour - -// mergeTrainLateFactor: a turn still pending this many times past its -// first estimate reads "running late". -const mergeTrainLateFactor = 2 - -func mergeTrainMemberKey(it *StageTrackerItem) string { - return it.Repo + "|" + strconv.Itoa(it.Number) -} - -// etaAnchor keeps a member's countdown steady across builds: the first -// estimate at a position is the anchor the SPA counts down to, and a -// re-estimate only moves it when it runs more than one sweep longer (the -// head's clock grew) — otherwise every poll would push the end out by the -// sweep it just waited. It also reports "running late": now past the -// first estimate mergeTrainLateFactor times over. -func (m *mergeTrainMemory) etaAnchor(self *StageTrackerItem, mt *StageTrackerMergeTrain, fresh, now time.Time, sweep time.Duration) (time.Time, bool) { - if m == nil || self == nil || mt == nil || mt.EtaS <= 0 { - return fresh, false - } - m.mu.Lock() - defer m.mu.Unlock() - if m.eta == nil { - m.eta = map[string]mergeTrainEtaMark{} - } - key := mergeTrainMemberKey(self) - mark, ok := m.eta[key] - if !ok || mark.Position != mt.Position || fresh.Sub(now) > mark.Eta+sweep { - m.eta[key] = mergeTrainEtaMark{At: now, Eta: time.Duration(mt.EtaS) * time.Second, Position: mt.Position} - return fresh, false - } - anchor := mark.At.Add(mark.Eta) - if anchor.Before(now) { - anchor = fresh - } - return anchor, now.Sub(mark.At) > mergeTrainLateFactor*mark.Eta -} - -// forgetEta drops the member's mark: a blocked member starts a fresh -// estimate once it is unblocked. -func (m *mergeTrainMemory) forgetEta(self *StageTrackerItem) { - if m == nil || self == nil { - return - } - m.mu.Lock() - delete(m.eta, mergeTrainMemberKey(self)) - m.mu.Unlock() -} - -// warn logs the stalled train once per hour; it returns true when it logged. -func (m *mergeTrainMemory) warn(repo string, mt *StageTrackerMergeTrain, now time.Time) bool { - if m == nil || mt == nil || !mt.Stalled { - return false - } - m.mu.Lock() - defer m.mu.Unlock() - if m.last == nil { - m.last = map[string]time.Time{} - } - key := repo + "|" + mt.ID - if at, ok := m.last[key]; ok && now.Sub(at) < mergeTrainStallLogEvery { - return false - } - m.last[key] = now - slog.Warn("merge train stalled: head has not progressed; "+strconv.Itoa(mt.Size-1)+" PR(s) wait behind it", - "repo", repo, "train", mt.ID, "head", mt.HeadNumber, "head_state", mt.HeadState, "head_reason", mt.HeadReason, "stalled_for", shortDuration(time.Duration(mt.StalledS)*time.Second), "size", mt.Size) - return true -} - -// stageTrackerMergeTrainStallWarnings runs the hourly log over the items: -// one line per stalled train, read from any member. -func stageTrackerMergeTrainStallWarnings(mem *mergeTrainMemory, items []StageTrackerItem, now time.Time) { - seen := map[string]bool{} - for i := range items { - mt := items[i].MergeTrain - if mt == nil || !mt.Stalled { - continue - } - key := items[i].Repo + "|" + mt.ID - if seen[key] { - continue - } - seen[key] = true - mem.warn(items[i].Repo, mt, now) - } -} - -// stageTrackerMergeTrainFrontCaption is the 080 caption of a train's front. -func stageTrackerMergeTrainFrontCaption(mt *StageTrackerMergeTrain) string { - files := "" - if len(mt.OverlapFiles) > 0 { - files = " (overlapping files: " + strings.Join(mt.OverlapFiles, ", ") + ")" - } - return "1st in a merge queue of " + strconv.Itoa(mt.Size) + " PRs; merges next, then the lane updates or rebases the others" + files -} - -// stageTrackerMergeTrainCaption is the caption for a sibling's train -// reason at 080 / 085 ("" when the reason is not a train reason). -func stageTrackerMergeTrainCaption(reason string) string { - mt, ok := prstage.ParseMergeTrain(reason) - if !ok { - return "" - } - onto := "the base" - if mt.Front > 0 { - onto = "the merged front #" + strconv.Itoa(mt.Front) - } - switch mt.State { - case prstage.MergeTrainStateRebasing: - return "Conflicts with " + onto + "; the hive is rebasing this PR (attempt " + strconv.Itoa(mt.Attempt) + " of " + strconv.Itoa(mt.MaxAttempts) + ")" - case prstage.MergeTrainStateRebaseExhausted: - return "The rebase onto " + onto + " failed " + strconv.Itoa(mt.Attempt) + " times; a maintainer rebases and merges" - default: - return "Approved; waiting its turn in the merge train — " + mt.Sentence() - } -} - -// decisionForMergeTrain: the train gave up rebasing this PR after the loop -// guard (hivecommons/hive#15117). The lead option is the rebase-then-merge -// follow-through (hivecommons/hive#15104): the click records the approval, -// re-opens the rebase episode in the operator's name and merges on green. -func decisionForMergeTrain(it StageTrackerItem, held bool) *StageTrackerDecision { - mt := it.MergeTrain - d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByLane, BlockerReason: it.Reason} - onto := "the base" - if mt.Front > 0 { - onto = "the merged front #" + strconv.Itoa(mt.Front) - } - d.Question = "The merge train could not rebase this PR onto " + onto + " after " + strconv.Itoa(mt.Attempt) + " attempts (overlapping files: " + strings.Join(mt.OverlapFiles, ", ") + "). Rebase it by hand and merge as maintainer, or close it?" - d.Blocker = "The rebase failed " + strconv.Itoa(mt.Attempt) + " of " + strconv.Itoa(mt.MaxAttempts) + " times; the train does not retry past the loop guard." - if held { - d.Blocker += " " + decisionHeldBlocker(it.Hold) - } - mergeNow := decisionOption(decisionActionMergeNow, rebaseMergeFollowThroughLabel, !held, decisionWhyHeld) - mergeNow.Consequence = rebaseMergeFollowThroughConsequence(it.Number, strings.TrimSpace(it.BaseRef)) - d.Options = []StageTrackerDecisionOption{ - mergeNow, - decisionOption(decisionActionCloseSuperseded, "Close as superseded", !held, decisionWhyHeld), - decisionHoldOption(held), - } - return d -} diff --git a/src/pkg/dashboard/stage_tracker_merge_train_eta.go b/src/pkg/dashboard/stage_tracker_merge_train_eta.go new file mode 100644 index 0000000000..0e7ac13989 --- /dev/null +++ b/src/pkg/dashboard/stage_tracker_merge_train_eta.go @@ -0,0 +1,276 @@ +package dashboard + +import ( + "log/slog" + "strconv" + "strings" + "sync" + "time" + + "github.com/hivecommons/hive/pkg/stageengine/prstage" + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// mergeTrainEtaBasis is the short plain-English reading of the estimate: +// "2 ahead · head soaking 12m · next pass in 40s". +func mergeTrainEtaBasis(aheadN int, headState string, headLeft, own, tick time.Duration, sweeping bool) string { + var parts []string + switch aheadN { + case 0: + parts = append(parts, "1st in queue") + case 1: + parts = append(parts, "1 ahead") + default: + parts = append(parts, strconv.Itoa(aheadN)+" ahead") + } + if aheadN > 0 && headState == mergeTrainHeadSoaking && headLeft > 0 { + parts = append(parts, "head soaking "+shortDuration(headLeft)) + } else if aheadN > 0 && headState == mergeTrainHeadMerging { + parts = append(parts, "head merging") + } + if own > 0 { + parts = append(parts, "own soak "+shortDuration(own)) + } + if sweeping { + parts = append(parts, "pass running") + } else if tick > 0 { + parts = append(parts, "next pass in "+shortDuration(tick)) + } + return strings.Join(parts, " · ") +} + +// mergeTrainHeadState reads the head's current state, its plain-word +// reason, how long its own clock still runs (soak left, next sweep) and +// whether that clock is known at all (false on a person or CI). +func mergeTrainHeadState(head *StageTrackerItem, now time.Time) (state, reason string, remaining time.Duration, known bool) { + if head == nil { + return mergeTrainHeadUnknown, "the head of the train is not in this view", 0, false + } + mg := head.MergeGate + if mg != nil && mg.State == MergeGateStateMerging { + return mergeTrainHeadMerging, "merging now", 0, true + } + if mg != nil && mg.State == MergeGateStateMergeFailed { + return mergeTrainHeadReady, "GitHub refused the last merge; hive retries on its next pass", 0, false + } + switch head.Stage { + case trackerNumberReadyForHuman: + why := "waiting for a maintainer" + if head.HumanMergeReason != "" { + why += " (" + strings.ReplaceAll(head.HumanMergeReason, "-", " ") + ")" + } + return mergeTrainHeadNeedsHuman, why, 0, false + case trackerNumberNeedsDecision, trackerNumberIssueDecision: + return mergeTrainHeadNeedsHuman, "waiting for a human decision", 0, false + case stagelabels.MergeQueue.Number(): + return mergeTrainHeadMerging, "merging now", 0, true + case trackerNumberPreMergeSoak: + left := time.Duration(0) + if mg != nil && mg.SoakRemainingSeconds > 0 { + left = time.Duration(mg.SoakRemainingSeconds) * time.Second + } + if left <= 0 && head.Soak != nil && head.Soak.Until.After(now) { + left = head.Soak.Until.Sub(now) + } + if left > 0 { + return mergeTrainHeadSoaking, "soaking, " + shortDuration(left) + " left", left, true + } + return mergeTrainHeadSoaking, "soaked; hive merges it on its next pass", 0, true + case trackerNumberReviewed, trackerNumberReviewPending: + return mergeTrainHeadCI, "waiting for CI", 0, false + case trackerNumberFixing, trackerNumberReturned, trackerNumberNeedsAuthor: + return mergeTrainHeadFixing, "being fixed by its author", 0, false + } + if head.Hold != nil || head.NeedsHuman { + return mergeTrainHeadNeedsHuman, "waiting for a maintainer", 0, false + } + if head.Soak != nil && head.Soak.Until.After(now) { + left := head.Soak.Until.Sub(now) + return mergeTrainHeadSoaking, "soaking, " + shortDuration(left) + " left", left, true + } + var next time.Duration + if mg != nil && mg.NextSweepAt != nil && mg.NextSweepAt.After(now) { + next = mg.NextSweepAt.Sub(now) + } + return mergeTrainHeadReady, "approved and green; merges on hive's next pass", next, true +} + +// shortDuration is "12m" / "1h 05m" / "45s" for the chip's words. +func shortDuration(d time.Duration) string { + d = d.Round(time.Second) + if d < time.Minute { + return strconv.Itoa(int(d/time.Second)) + "s" + } + m := int(d / time.Minute) + if m < 60 { + return strconv.Itoa(m) + "m" + } + rem := m % 60 + if rem == 0 { + return strconv.Itoa(m/60) + "h" + } + rest := strconv.Itoa(rem) + if rem < 10 { + rest = "0" + rest + } + return strconv.Itoa(m/60) + "h " + rest + "m" +} + +// mergeTrainMemory is what the tracker keeps between builds for the +// trains: the hour-stamp of each stalled train's activity-log line and +// each member's first estimate (for "running late"). +type mergeTrainMemory struct { + mu sync.Mutex + last map[string]time.Time + eta map[string]mergeTrainEtaMark +} + +// mergeTrainEtaMark is a member's first estimate at a given position. +type mergeTrainEtaMark struct { + At time.Time + Eta time.Duration + Position int +} + +const mergeTrainStallLogEvery = time.Hour + +// mergeTrainLateFactor: a turn still pending this many times past its +// first estimate reads "running late". +const mergeTrainLateFactor = 2 + +func mergeTrainMemberKey(it *StageTrackerItem) string { + return it.Repo + "|" + strconv.Itoa(it.Number) +} + +// etaAnchor keeps a member's countdown steady across builds: the first +// estimate at a position is the anchor the SPA counts down to, and a +// re-estimate only moves it when it runs more than one sweep longer (the +// head's clock grew) — otherwise every poll would push the end out by the +// sweep it just waited. It also reports "running late": now past the +// first estimate mergeTrainLateFactor times over. +func (m *mergeTrainMemory) etaAnchor(self *StageTrackerItem, mt *StageTrackerMergeTrain, fresh, now time.Time, sweep time.Duration) (time.Time, bool) { + if m == nil || self == nil || mt == nil || mt.EtaS <= 0 { + return fresh, false + } + m.mu.Lock() + defer m.mu.Unlock() + if m.eta == nil { + m.eta = map[string]mergeTrainEtaMark{} + } + key := mergeTrainMemberKey(self) + mark, ok := m.eta[key] + if !ok || mark.Position != mt.Position || fresh.Sub(now) > mark.Eta+sweep { + m.eta[key] = mergeTrainEtaMark{At: now, Eta: time.Duration(mt.EtaS) * time.Second, Position: mt.Position} + return fresh, false + } + anchor := mark.At.Add(mark.Eta) + if anchor.Before(now) { + anchor = fresh + } + return anchor, now.Sub(mark.At) > mergeTrainLateFactor*mark.Eta +} + +// forgetEta drops the member's mark: a blocked member starts a fresh +// estimate once it is unblocked. +func (m *mergeTrainMemory) forgetEta(self *StageTrackerItem) { + if m == nil || self == nil { + return + } + m.mu.Lock() + delete(m.eta, mergeTrainMemberKey(self)) + m.mu.Unlock() +} + +// warn logs the stalled train once per hour; it returns true when it logged. +func (m *mergeTrainMemory) warn(repo string, mt *StageTrackerMergeTrain, now time.Time) bool { + if m == nil || mt == nil || !mt.Stalled { + return false + } + m.mu.Lock() + defer m.mu.Unlock() + if m.last == nil { + m.last = map[string]time.Time{} + } + key := repo + "|" + mt.ID + if at, ok := m.last[key]; ok && now.Sub(at) < mergeTrainStallLogEvery { + return false + } + m.last[key] = now + slog.Warn("merge train stalled: head has not progressed; "+strconv.Itoa(mt.Size-1)+" PR(s) wait behind it", + "repo", repo, "train", mt.ID, "head", mt.HeadNumber, "head_state", mt.HeadState, "head_reason", mt.HeadReason, "stalled_for", shortDuration(time.Duration(mt.StalledS)*time.Second), "size", mt.Size) + return true +} + +// stageTrackerMergeTrainStallWarnings runs the hourly log over the items: +// one line per stalled train, read from any member. +func stageTrackerMergeTrainStallWarnings(mem *mergeTrainMemory, items []StageTrackerItem, now time.Time) { + seen := map[string]bool{} + for i := range items { + mt := items[i].MergeTrain + if mt == nil || !mt.Stalled { + continue + } + key := items[i].Repo + "|" + mt.ID + if seen[key] { + continue + } + seen[key] = true + mem.warn(items[i].Repo, mt, now) + } +} + +// stageTrackerMergeTrainFrontCaption is the 080 caption of a train's front. +func stageTrackerMergeTrainFrontCaption(mt *StageTrackerMergeTrain) string { + files := "" + if len(mt.OverlapFiles) > 0 { + files = " (overlapping files: " + strings.Join(mt.OverlapFiles, ", ") + ")" + } + return "1st in a merge queue of " + strconv.Itoa(mt.Size) + " PRs; merges next, then the lane updates or rebases the others" + files +} + +// stageTrackerMergeTrainCaption is the caption for a sibling's train +// reason at 080 / 085 ("" when the reason is not a train reason). +func stageTrackerMergeTrainCaption(reason string) string { + mt, ok := prstage.ParseMergeTrain(reason) + if !ok { + return "" + } + onto := "the base" + if mt.Front > 0 { + onto = "the merged front #" + strconv.Itoa(mt.Front) + } + switch mt.State { + case prstage.MergeTrainStateRebasing: + return "Conflicts with " + onto + "; the hive is rebasing this PR (attempt " + strconv.Itoa(mt.Attempt) + " of " + strconv.Itoa(mt.MaxAttempts) + ")" + case prstage.MergeTrainStateRebaseExhausted: + return "The rebase onto " + onto + " failed " + strconv.Itoa(mt.Attempt) + " times; a maintainer rebases and merges" + default: + return "Approved; waiting its turn in the merge train — " + mt.Sentence() + } +} + +// decisionForMergeTrain: the train gave up rebasing this PR after the loop +// guard (hivecommons/hive#15117). The lead option is the rebase-then-merge +// follow-through (hivecommons/hive#15104): the click records the approval, +// re-opens the rebase episode in the operator's name and merges on green. +func decisionForMergeTrain(it StageTrackerItem, held bool) *StageTrackerDecision { + mt := it.MergeTrain + d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByLane, BlockerReason: it.Reason} + onto := "the base" + if mt.Front > 0 { + onto = "the merged front #" + strconv.Itoa(mt.Front) + } + d.Question = "The merge train could not rebase this PR onto " + onto + " after " + strconv.Itoa(mt.Attempt) + " attempts (overlapping files: " + strings.Join(mt.OverlapFiles, ", ") + "). Rebase it by hand and merge as maintainer, or close it?" + d.Blocker = "The rebase failed " + strconv.Itoa(mt.Attempt) + " of " + strconv.Itoa(mt.MaxAttempts) + " times; the train does not retry past the loop guard." + if held { + d.Blocker += " " + decisionHeldBlocker(it.Hold) + } + mergeNow := decisionOption(decisionActionMergeNow, rebaseMergeFollowThroughLabel, !held, decisionWhyHeld) + mergeNow.Consequence = rebaseMergeFollowThroughConsequence(it.Number, strings.TrimSpace(it.BaseRef)) + d.Options = []StageTrackerDecisionOption{ + mergeNow, + decisionOption(decisionActionCloseSuperseded, "Close as superseded", !held, decisionWhyHeld), + decisionHoldOption(held), + } + return d +} diff --git a/src/pkg/dashboard/stage_tracker_merge_train_overlap.go b/src/pkg/dashboard/stage_tracker_merge_train_overlap.go new file mode 100644 index 0000000000..f2a0bfe36d --- /dev/null +++ b/src/pkg/dashboard/stage_tracker_merge_train_overlap.go @@ -0,0 +1,146 @@ +package dashboard + +import ( + "reflect" + "strconv" + "strings" + + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// StageTrackerOverlap is the hint on a PR short of the merge queue whose +// files overlap another open PR's: Behind is the PR it will queue behind +// once both are merge-ready (0 when this one is the planner's front), +// With the other overlapping PRs, Files the overlapping files and Note +// the one line the row shows — "overlaps #15637 (sidebar.html, +// index.html) — will queue behind it". The row has no merge_train, no +// ordinal and no rail: the train starts at 080. +type StageTrackerOverlap struct { + Behind int `json:"behind,omitempty"` + With []int `json:"with,omitempty"` + Files []string `json:"files,omitempty"` + Note string `json:"note"` + // trainID and position remember the planner's slot so the members + // that do ride can close ranks (stageTrackerMergeTrainPostPass). + trainID string + position int +} + +// stageTrackerOverlapHint builds the hint for a PR at number, out of a +// train whose planner's front is front and whose other members are +// others (number excluded by the caller). +func stageTrackerOverlapHint(number, front int, others []int, files []string) *StageTrackerOverlap { + o := &StageTrackerOverlap{With: append([]int(nil), others...), Files: append([]string(nil), files...)} + paren := "" + if len(files) > 0 { + paren = " (" + strings.Join(files, ", ") + ")" + } + if number != front && front > 0 { + o.Behind = front + o.Note = "overlaps #" + strconv.Itoa(front) + paren + " — will queue behind it" + return o + } + names := make([]string, 0, len(others)) + for _, n := range others { + names = append(names, "#"+strconv.Itoa(n)) + } + them := "it" + if len(others) > 1 { + them = "them" + } + o.Note = "overlaps " + strings.Join(names, ", ") + paren + " — merges ahead of " + them + " once both are ready" + if len(others) > 1 { + o.Note = strings.Replace(o.Note, "once both are ready", "once all are ready", 1) + } + return o +} + +// stageTrackerLeaveMergeTrainBelowQueue takes a PR short of the merge +// queue out of its train and leaves the overlap hint in its place. +func stageTrackerLeaveMergeTrainBelowQueue(it *StageTrackerItem, front int, others []int) { + if it == nil || it.MergeTrain == nil { + return + } + mt := it.MergeTrain + pos := mt.Position + if mt.State == MergeGateStateTrainFront { + pos = 1 + } + stageTrackerLeaveMergeTrain(it, "") + it.Overlap = stageTrackerOverlapHint(it.Number, front, others, mt.OverlapFiles) + it.Overlap.trainID, it.Overlap.position = mt.ID, pos +} + +// stageTrackerTrainUnderRepair names why a PR at stage, with reason, is +// not a train member right now — "" when it may ride. A PR being fixed +// (070), waiting on its author (071) or contributor (072), freshly +// adopted (074), parked on a human decision (085), or whose required +// checks are red is somebody's to repair first; the planner may still +// have ordered it, but the view never seats it. A PR short of the merge +// queue is not under repair but rides no train either +// (stageTrackerBelowMergeQueue). +// +// stageTrackerItemColumn reads the same predicate for the chevron +// column, and stageTrackerUnderRepair in the SPA mirrors it: membership +// and column can never disagree (hive's own #15574 sat at 070 "Fixing" +// under Merge queue because its stale merge-failed gate still promoted +// the column after the train rule had already dropped it). +func stageTrackerTrainUnderRepair(stage int, reason string) string { + switch stage { + case stagelabels.Fixing.Number(): + return stagelabels.Fixing.Slug() + case stagelabels.NeedsAuthor.Number(): + return stagelabels.NeedsAuthor.Slug() + case stagelabels.ReturnedToContributor.Number(): + return stagelabels.ReturnedToContributor.Slug() + case stagelabels.AdoptedByHive.Number(): + return stagelabels.AdoptedByHive.Slug() + case stagelabels.NeedsDecision.Number(): + return stagelabels.NeedsDecision.Slug() + } + lower := strings.ToLower(strings.TrimSpace(reason)) + if strings.HasPrefix(lower, "required-check-failing:") || strings.HasPrefix(lower, "check-failing:") || lower == "ci-red" { + return "checks-failing" + } + return "" +} + +// stageTrackerLeaveMergeTrain takes a PR out of its train: the train +// record and the train's gate words go, and LeftTrain keeps why (and, +// unexported, which train and which slot) so the row can say so on hover +// and the survivors can close ranks. why "" (a train that shrank to one +// member) leaves no note — there is no train to have left. +func stageTrackerLeaveMergeTrain(it *StageTrackerItem, why string) { + if it == nil || it.MergeTrain == nil { + return + } + mt := it.MergeTrain + if it.MergeGate != nil && (it.MergeGate.State == mt.State || it.MergeGate.State == MergeGateStateTrainFront) { + // Back to the stage's own gate state (ready at 080, pending at + // 060); off the gate there is no gate. + it.MergeGate.State = "" + switch it.Stage { + case stagelabels.Reviewed.Number(): + it.MergeGate.State = MergeGateStatePending + case stagelabels.AwaitingMergeAdmission.Number(): + it.MergeGate.State = MergeGateStateReady + } + it.MergeGate.Reason = "" + if it.MergeGate.State == "" || reflect.DeepEqual(*it.MergeGate, StageTrackerMergeGate{}) { + it.MergeGate = nil + } + } + it.MergeTrain = nil + // The caption the train wrote ("waiting its turn … behind #N") is + // stale now; an 080 row goes back to the gate's own words. + if it.Stage == stagelabels.AwaitingMergeAdmission.Number() && (it.Caption == stageTrackerMergeTrainCaption(it.Reason) || it.Caption == stageTrackerMergeTrainFrontCaption(mt)) { + it.Caption = stageTrackerAwaitingAdmissionCaption + } + if why != "" { + pos := mt.Position + if mt.State == MergeGateStateTrainFront { + pos = 1 + } + it.LeftTrain = &StageTrackerLeftTrain{Why: why, Note: stageTrackerLeftTrainNote, trainID: mt.ID, position: pos} + } +} diff --git a/src/pkg/dashboard/stage_tracker_merge_train_postpass.go b/src/pkg/dashboard/stage_tracker_merge_train_postpass.go new file mode 100644 index 0000000000..c940ed3b3f --- /dev/null +++ b/src/pkg/dashboard/stage_tracker_merge_train_postpass.go @@ -0,0 +1,319 @@ +package dashboard + +import ( + "sort" + "strconv" + "strings" + "time" + + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// stageTrackerMergeTrainFrontGate words the gate of the member merging +// first: "1st in the merge queue; merges next (1st of 2, overlapping +// files: a.go)". promoted is a member that was queued behind a front +// that just left: its queued words are stale and are replaced. +func stageTrackerMergeTrainFrontGate(front *StageTrackerItem, size int, files []string, promoted bool) { + if front.MergeGate == nil { + front.MergeGate = &StageTrackerMergeGate{} + } + if front.MergeGate.State == "" || front.MergeGate.State == MergeGateStateReady || (promoted && front.MergeGate.State == MergeGateStateQueuedBehind) { + front.MergeGate.State = MergeGateStateTrainFront + } + if front.MergeGate.Reason == "" || promoted { + front.MergeGate.Reason = "1st in the merge queue; merges next (1st of " + strconv.Itoa(size) + ", overlapping files: " + strings.Join(files, ", ") + ")" + } +} + +// stageTrackerMergeTrainPostPass runs over the finished items: the front +// (which the lane evaluates on its normal path and so carries no train +// reason) is marked from its siblings' records, and every member learns +// the PRs ahead of it. Members are matched on repo and base. A member +// under repair (stageTrackerTrainUnderRepair) leaves the train first — +// the front included — as does one short of the merge queue +// (stageTrackerBelowMergeQueue, which keeps an overlap hint instead); +// the rest close ranks (size, place, front and ahead recomputed), and a +// train left with one member is no train at all: no header, no ordinal +// (hivecommons/hive#15405 led a header as "1st: #15405" while its own +// chevron read "Fixing"; hive's own #15637/#15633 led one while both +// read CI / Review). +func stageTrackerMergeTrainPostPass(items []StageTrackerItem, opts mergeTrainQueueOptions, mem *mergeTrainMemory) { + type trainKey struct{ repo, id string } + // Every row the planner ordered, by train, before the view decides who + // rides; the overlap hint on a row that does not names the rest. + ordered := map[trainKey][]int{} + samples := map[trainKey]*StageTrackerMergeTrain{} + var keys []trainKey + for i := range items { + it := &items[i] + if it.MergeTrain == nil || it.Kind != "pr" { + continue + } + k := trainKey{it.Repo, it.MergeTrain.ID} + if _, seen := samples[k]; !seen { + samples[k] = it.MergeTrain + keys = append(keys, k) + } + ordered[k] = append(ordered[k], i) + } + for _, key := range keys { + sample := *samples[key] + frontIdx := -1 + for i := range items { + it := &items[i] + if it.Kind == "pr" && it.Repo == key.repo && it.Number == sample.Front && it.Stage < stageTrackerMergedStage { + frontIdx = i + break + } + } + roster := func(except int) []int { + var out []int + if frontIdx >= 0 && items[frontIdx].Number != except { + out = append(out, items[frontIdx].Number) + } + for _, i := range ordered[key] { + if items[i].Number != except { + out = append(out, items[i].Number) + } + } + sort.Ints(out) + return out + } + var idx []int + for _, i := range ordered[key] { + it := &items[i] + // A rebase-exhausted tail sits at 085 by the train's own doing; + // it stays so the person who rebases it sees where it merges. + if it.MergeTrain.State != MergeGateStateRebaseExhausted { + if why := stageTrackerTrainUnderRepair(it.Stage, it.Reason); why != "" { + stageTrackerLeaveMergeTrain(it, why) + continue + } + if stageTrackerBelowMergeQueue(it.Stage) { + stageTrackerLeaveMergeTrainBelowQueue(it, sample.Front, roster(it.Number)) + continue + } + } + idx = append(idx, i) + } + frontLeft := false + if frontIdx >= 0 && items[frontIdx].MergeTrain == nil { + front := &items[frontIdx] + if why := stageTrackerTrainUnderRepair(front.Stage, front.Reason); why != "" { + front.LeftTrain = &StageTrackerLeftTrain{Why: why, Note: stageTrackerLeftTrainNote, trainID: sample.ID, position: 1} + frontLeft = true + } else if stageTrackerBelowMergeQueue(front.Stage) { + front.Overlap = stageTrackerOverlapHint(front.Number, sample.Front, roster(front.Number), sample.OverlapFiles) + front.Overlap.trainID, front.Overlap.position = sample.ID, 1 + frontLeft = true + } else { + front.MergeTrain = &StageTrackerMergeTrain{ + ID: sample.ID, State: MergeGateStateTrainFront, Front: sample.Front, Position: 1, Size: sample.Size, + OverlapFiles: append([]string(nil), sample.OverlapFiles...), + } + stageTrackerMergeTrainFrontGate(front, sample.Size, sample.OverlapFiles, false) + if front.Stage == stagelabels.AwaitingMergeAdmission.Number() { + front.Caption = stageTrackerMergeTrainFrontCaption(&sample) + } + idx = append(idx, frontIdx) + } + } + if len(idx) == 0 { + continue + } + // The queue is the members that ride in this payload — never the + // planner's count, which includes PRs the view does not seat + // (below 080, under repair, a record another lane overwrote): + // hive's own header read "2 of 9 PRs here · not in this view: 7 + // more" over the only two PRs actually queued (hivecommons/hive#15653). + // Members the view sent elsewhere; one survivor is no train. + var dropped []int + for i := range items { + it := &items[i] + if it.Kind != "pr" || it.Repo != key.repo || it.MergeTrain != nil { + continue + } + if it.LeftTrain != nil && it.LeftTrain.trainID == sample.ID { + dropped = append(dropped, it.LeftTrain.position) + } else if it.Overlap != nil && it.Overlap.trainID == sample.ID { + dropped = append(dropped, it.Overlap.position) + } + } + if len(dropped) > 0 { + if sample.Size-len(dropped) < 2 { + for _, i := range idx { + stageTrackerLeaveMergeTrain(&items[i], "") + } + continue + } + } + // Riders keep their planner order but take slots 1..N: a member + // the planner seated 5th of 9 whose seven neighbours never rode + // (below the merge queue, under repair, or not in this payload) + // is 2nd of 2 here, never "5th of 2". + sort.Slice(idx, func(a, b int) bool { + return items[idx[a]].MergeTrain.Position < items[idx[b]].MergeTrain.Position + }) + for n, i := range idx { + items[i].MergeTrain.Position = n + 1 + } + for _, i := range idx { + mt := items[i].MergeTrain + mt.Size = len(idx) + // The front's gate and caption counted the planner's size; + // say the size of the train that rides. + if mt.State == MergeGateStateTrainFront && mt.Size != sample.Size { + front := &items[i] + stageTrackerMergeTrainFrontGate(front, mt.Size, mt.OverlapFiles, true) + if front.Stage == stagelabels.AwaitingMergeAdmission.Number() && front.Caption == stageTrackerMergeTrainFrontCaption(&sample) { + front.Caption = stageTrackerMergeTrainFrontCaption(mt) + } + } + } + // Members in merge order, so each one's Ahead is the prefix. + if frontLeft { + // The old front is out; the member now in slot 1 leads. + newFront := 0 + if first := &items[idx[0]]; first.MergeTrain.Position == 1 { + newFront = first.Number + first.MergeTrain.State = MergeGateStateTrainFront + stageTrackerMergeTrainFrontGate(first, first.MergeTrain.Size, first.MergeTrain.OverlapFiles, true) + frontIdx = idx[0] + } + for _, i := range idx { + items[i].MergeTrain.Front = newFront + } + } + members := make([]int, 0, len(idx)) + for _, i := range idx { + members = append(members, items[i].Number) + } + for n, i := range idx { + var ahead []int + for _, j := range idx[:n] { + ahead = append(ahead, items[j].Number) + } + items[i].MergeTrain.Ahead = ahead + items[i].MergeTrain.Members = append([]int(nil), members...) + } + var head *StageTrackerItem + if frontIdx >= 0 { + head = &items[frontIdx] + } + for n, i := range idx { + ahead := make([]*StageTrackerItem, 0, n) + for _, j := range idx[:n] { + ahead = append(ahead, &items[j]) + } + stageTrackerMergeTrainQueueFacts(&items[i], ahead, head, opts, mem) + } + } +} + +// stageTrackerMergeTrainQueueFacts fills the chip's queue facts on one +// member: what the head is doing, how long it has sat there, the estimate +// of this member's own turn and whether the train reads stalled. ahead is +// every member before this one in merge order (the head first, when it is +// in the view); mem remembers each member's first estimate so a turn that +// has overrun it twice over reads "running late". +func stageTrackerMergeTrainQueueFacts(self *StageTrackerItem, ahead []*StageTrackerItem, head *StageTrackerItem, opts mergeTrainQueueOptions, mem *mergeTrainMemory) { + if self == nil || self.MergeTrain == nil { + return + } + mt := self.MergeTrain + mt.Length = mt.Size + mt.HeadNumber = mt.Front + state, reason, headLeft, known := mergeTrainHeadState(head, opts.Now) + mt.HeadState, mt.HeadReason = state, reason + if head != nil && head.StageSince != nil && !head.StageSince.IsZero() { + since := *head.StageSince + mt.HeadSince = &since + } + mt.EtaS, mt.EtaAt, mt.EtaBasis, mt.Late = 0, nil, "", false + // Stalled: the head has sat in its stage past the warn window and is + // not actually merging. A soaking head is on its clock, not stalled, + // until that clock has itself overrun the window. + if opts.StallWarn > 0 && mt.HeadSince != nil && state != mergeTrainHeadMerging && state != mergeTrainHeadUnknown { + sat := opts.Now.Sub(*mt.HeadSince) + if sat > opts.StallWarn && !(state == mergeTrainHeadSoaking && headLeft > 0) { + mt.Stalled = true + mt.StalledS = int64(sat / time.Second) + } + } + // No estimate while the head (or this member) waits on a person or on + // CI: the blocker is the word, not a clock. + if !known || self.NeedsHuman || self.Hold != nil { + if mem != nil { + mem.forgetEta(self) + } + return + } + // The estimate (hivecommons/hive#15395): this member's own soak left, + // plus each PR ahead — its remaining soak, or one sweep when it has + // none — plus the wait for the next sweep tick. + sweep := opts.Sweep + if sweep <= 0 { + sweep = mergeTrainDefaultSweepEvery + } + var eta time.Duration + own := stageTrackerSoakLeftOf(self, opts.Now) + eta += own + for i, a := range ahead { + left := stageTrackerSoakLeftOf(a, opts.Now) + if i == 0 && a == head { + left = headLeft + } + if left <= 0 { + left = sweep + } + eta += left + } + tick := opts.NextSweepIn(self) + eta += tick + if eta < time.Second { + eta = time.Second + } + mt.EtaS = int64(eta / time.Second) + at := opts.Now.Add(eta) + mt.EtaBasis = mergeTrainEtaBasis(len(ahead), state, headLeft, own, tick, self.MergeGate != nil && self.MergeGate.SweepRunning) + if mem != nil { + at, mt.Late = mem.etaAnchor(self, mt, at, opts.Now, sweep) + } + mt.EtaAt = &at +} + +// mergeTrainDefaultSweepEvery stands in for the lanes' floor cadence +// before the sweep loop has armed it (automerge's floor interval). +const mergeTrainDefaultSweepEvery = 5 * time.Minute + +// NextSweepIn is how long until the next sweep tick: the member's own +// next_sweep_at when the gate carries one, else the lanes' floor; 0 while +// a sweep runs or none is armed. +func (o mergeTrainQueueOptions) NextSweepIn(self *StageTrackerItem) time.Duration { + if self != nil && self.MergeGate != nil { + if self.MergeGate.SweepRunning { + return 0 + } + if self.MergeGate.NextSweepAt != nil && self.MergeGate.NextSweepAt.After(o.Now) { + return self.MergeGate.NextSweepAt.Sub(o.Now) + } + } + if !o.NextSweepAt.IsZero() && o.NextSweepAt.After(o.Now) { + return o.NextSweepAt.Sub(o.Now) + } + return 0 +} + +// stageTrackerSoakLeftOf is how much of an item's own soak clock remains. +func stageTrackerSoakLeftOf(it *StageTrackerItem, now time.Time) time.Duration { + if it == nil { + return 0 + } + if it.MergeGate != nil && it.MergeGate.SoakRemainingSeconds > 0 { + return time.Duration(it.MergeGate.SoakRemainingSeconds) * time.Second + } + if it.Soak != nil && it.Soak.Until.After(now) { + return it.Soak.Until.Sub(now) + } + return 0 +}