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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/fixed-needs-decision-empty-reasons.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The `stage/085-needs-decision` comment always says why a decision is needed. When a PR was held at 085 on the same head after the contributor lane's own read of the reviewer verdict came back empty, the hive re-parked it with a bare route and posted "Needs a decision, not a merge:" followed by nothing, although the stage pass held the reviewer's `requires_human` verdict and finding ([projectbluefin/fsdk-containers#553](https://github.com/projectbluefin/fsdk-containers/pull/553)). The re-park now carries the reviewer's verdict, finding and question; the shared-CI permission park carries its cause; and any 085 route that still has no reason renders "the reviewer asked for a human decision" with a warning in the hive log naming the PR and head.
8 changes: 8 additions & 0 deletions src/docs/labels-and-control-signals/stage-labels.md
Original file line number Diff line number Diff line change
Expand Up @@ -483,6 +483,14 @@ maintainer's behalf, so prow/tide see nothing until a person acts. The
check digest costs two REST calls per head and is cached 10 minutes; it is
read only for human-routed PRs.

The 085 comment always names a cause. A PR the stage pass holds at 085 on
the same head, after the lane's own route came back without a decision, is
re-parked with the reviewer's `requires_human` verdict, finding and question
from the stage pass's verdict read. A route that still reaches 085 with no
reason renders "Needs a decision, not a merge: the reviewer asked for a human
decision." and the hive logs a warning naming the PR, head and lane reason
([projectbluefin/fsdk-containers#553](https://github.com/projectbluefin/fsdk-containers/pull/553)).

### `role/*` — would the hive auto-merge this?

One per PR, derived from what the lane used for admission (registry tier,
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
package automerge

import (
"strings"
"testing"

"github.com/hivecommons/hive/pkg/stagelabels"
)

// TestSameHeadDecisionRouteNamesReviewerFinding pins
// projectbluefin/fsdk-containers#553: the same-head 085 re-park carried an
// empty route, and the entry comment read "Needs a decision, not a merge:"
// with no reason, while the stage pass held the reviewer's requires_human
// verdict and its finding. The re-park's route now names them.
func TestSameHeadDecisionRouteNamesReviewerFinding(t *testing.T) {
head := "0afe7c60b570d5b04dd2967459ab41797f4af639"
obs := stageObservation{HeadSHA: head, Lane: stageLaneContributor}
obs.Detail.VerdictKnown = true
obs.Detail.Verdict = ContributorLaneVerdict{
Configured: true,
Verdict: "requires_human",
DecisionRequested: true,
DecisionFinding: "the reviewer marked this change high-risk",
}
route := sameHeadDecisionRoute(obs)
if route.Stage != stagelabels.NeedsDecision || route.Head != head || route.Verdict != stagelabels.VerdictRequiresHuman || route.SelfAuthored {
t.Fatalf("route = %+v", route)
}
body := stagelabels.DecisionComment(route)
for _, want := range []string{
"- the reviewer swarm returned `requires_human` @0afe7c6\n",
"- the review found: the reviewer marked this change high-risk\n",
} {
if !strings.Contains(body, want) {
t.Fatalf("DecisionComment missing %q:\n%s", want, body)
}
}

self := stageObservation{HeadSHA: head, Lane: stageLaneSelf}
if r := sameHeadDecisionRoute(self); !r.SelfAuthored || len(r.Reasons) != 0 {
t.Fatalf("self-authored route with no verdict = %+v", r)
} else if body := stagelabels.DecisionComment(r); !strings.Contains(body, "Needs a decision, not a merge: "+stagelabels.DecisionReasonUnnamed+".") {
t.Fatalf("no verdict known: DecisionComment =\n%s", body)
}
}
26 changes: 26 additions & 0 deletions src/pkg/github/automerge/automerge_stage_human.go
Original file line number Diff line number Diff line change
Expand Up @@ -819,6 +819,27 @@ func joinNames(names []string) string {
// reasons of its own (trust is the only objection).
var readyEntryCause = stagelabels.EntryCause([]string{"ready for a human merge"})

// sameHeadDecisionRoute is the 085 route preserveNeedsDecisionOnSameHead
// re-parks a head on. The human route built this pass can disagree with
// the stage pass's own verdict read: on projectbluefin/fsdk-containers#553
// the contributor lane's verdict cache read no verdict while the stage pass
// held `requires_human` with its finding, the route came back without a
// decision, and the re-park posted "Needs a decision, not a merge:" with no
// reason at all. The reasons come from the stage pass's verdict instead;
// with no verdict known for the head the comment names
// stagelabels.DecisionReasonUnnamed.
func sameHeadDecisionRoute(obs stageObservation) stagelabels.Route {
route := stagelabels.Route{Stage: stagelabels.NeedsDecision, Head: obs.HeadSHA, SelfAuthored: obs.Lane == stageLaneSelf,
Holds: stagelabels.Holds(obs.Labels), Hold: obs.Hold}
if !obs.Detail.VerdictKnown {
return route
}
v := normalizeContributorLaneVerdict(obs.Detail.Verdict)
route.Verdict = stagelabels.VerdictRequiresHuman
route.Reasons = stagelabels.RequiresHumanReasons(obs.HeadSHA, v.DecisionFinding, v.DecisionQuestion, v.HumanSummaries)
return route
}

func (c *Engine) postHumanEntry(ctx context.Context, store *stagelabels.Store, key string, obs stageObservation, role stagelabels.Role, route stagelabels.Route) (int, error) {
rec, ok := store.Get(key)
if !ok || rec.Stage != route.Stage {
Expand Down Expand Up @@ -871,6 +892,11 @@ func (c *Engine) postHumanEntry(ctx context.Context, store *stagelabels.Store, k
case stagelabels.ReadyForHumanMerge:
body = stagelabels.ReadyComment(route, trustCause(obs.Reason, role))
case stagelabels.NeedsDecision:
if len(route.Reasons) == 0 {
// The comment falls back to DecisionReasonUnnamed; name the
// route that carried no reason so it can be found.
c.warn("stage labels: 085 route carries no reason; the entry comment names a generic one", "repo", obs.Display, "pr", obs.Number, "head", obs.HeadSHA, "reason", obs.Reason, "lane", obs.Lane)
}
body = stagelabels.DecisionComment(route) + c.workflowApprovalSnippet(obs.Reason)
default:
return 0, nil
Expand Down
5 changes: 4 additions & 1 deletion src/pkg/github/automerge/automerge_stage_labels.go
Original file line number Diff line number Diff line change
Expand Up @@ -1450,6 +1450,9 @@ func (c *Engine) ApplyStageLabels(ctx context.Context) (StageLabelResult, error)
verdict.Rank = stageRankOwned
obs.Reason = unauthorizedReason(step)
route := stagelabels.Route{Stage: stagelabels.NeedsDecision}
if cause := decisionCause(obs.Reason); cause != "" {
route.Reasons = []string{cause}
}
obs.Route = &route
}
// Only re-park when the post-steps would leave 085: an adoption
Expand All @@ -1458,7 +1461,7 @@ func (c *Engine) ApplyStageLabels(ctx context.Context) (StageLabelResult, error)
if replacement, ok := preserveNeedsDecisionOnSameHead(prevRec, hadPrev, obs, verdict); ok {
verdict = replacement
obs.Reason = replacement.Reason
route := stagelabels.Route{Stage: stagelabels.NeedsDecision}
route := sameHeadDecisionRoute(obs)
obs.Route = &route
}
}
Expand Down
58 changes: 38 additions & 20 deletions src/pkg/stagelabels/human.go
Original file line number Diff line number Diff line change
Expand Up @@ -482,6 +482,34 @@ func ParseFixerExhausted(reason string) (attempts int, ok bool) {
// specific cause; EntryCause leaves it out of the dedup digest.
const decisionConsequenceReason = "the automerge lane will not merge this unattended"

// RequiresHumanReasons are the 085 reasons for a reviewer `requires_human`
// verdict on head: the verdict itself, the finding behind it, and the
// reviewer's question (else its human-facing summaries).
func RequiresHumanReasons(head, finding, question string, summaries []string) []string {
reasons := []string{"the reviewer swarm returned `requires_human` @" + ShortSHA(head)}
if f := strings.TrimSpace(finding); f != "" {
reasons = append(reasons, "the review found: "+f)
}
if q := strings.TrimSpace(question); q != "" {
if decisionQuestionPlaceholderMention(q) {
q += " _(the reviewer named no specific person; repository approvers/owners, this is yours)_"
}
reasons = append(reasons, "reviewer question: "+q)
} else {
for _, summary := range summaries {
if s := strings.TrimSpace(summary); s != "" {
reasons = append(reasons, "reviewer summary: "+s)
}
}
}
return reasons
}

// DecisionReasonUnnamed is the 085 entry comment's reason when the route
// reached it with none: the note always names a cause, never an empty list
// (projectbluefin/fsdk-containers#553).
const DecisionReasonUnnamed = "the reviewer asked for a human decision"

// RouteHuman decides which stage a lane's "a human must act" resolves to.
func RouteHuman(e Evidence) Route {
return withGates(e, routeProgress(e))
Expand Down Expand Up @@ -665,22 +693,7 @@ func routeProgress(e Evidence) Route {
// head: the decision is made, not owed.
break
}
decide = append(decide, "the reviewer swarm returned `requires_human` @"+ShortSHA(e.Head))
if f := strings.TrimSpace(e.DecisionFinding); f != "" {
decide = append(decide, "the review found: "+f)
}
if q := strings.TrimSpace(e.DecisionQuestion); q != "" {
if decisionQuestionPlaceholderMention(q) {
q += " _(the reviewer named no specific person; repository approvers/owners, this is yours)_"
}
decide = append(decide, "reviewer question: "+q)
} else {
for _, summary := range e.HumanSummaries {
if s := strings.TrimSpace(summary); s != "" {
decide = append(decide, "reviewer summary: "+s)
}
}
}
decide = append(decide, RequiresHumanReasons(e.Head, e.DecisionFinding, e.DecisionQuestion, e.HumanSummaries)...)
}
// A sentinel alert or a hold-class label is a gate, not a stage
// (hivecommons/hive#17327): withGates rides it on whatever stage the
Expand Down Expand Up @@ -955,7 +968,8 @@ func readyCommentBehindTail(r Route) string {
"\n\n<sub>The hive never approves on your behalf: `/lgtm` `/approve` if you accept it; the branch still has to be brought up to date before it can merge.</sub>"
}

// DecisionComment renders the 085 entry comment naming what is owed.
// DecisionComment renders the 085 entry comment naming what is owed. A
// route with no reasons names DecisionReasonUnnamed instead of an empty list.
func DecisionComment(r Route) string {
var b strings.Builder
b.WriteString(DecisionCommentMarker)
Expand All @@ -964,13 +978,17 @@ func DecisionComment(r Route) string {
} else {
b.WriteString("\nNeeds a decision, not a merge")
}
if len(r.Reasons) == 1 {
reasons := r.Reasons
if len(reasons) == 0 {
reasons = []string{DecisionReasonUnnamed}
}
if len(reasons) == 1 {
b.WriteString(": ")
b.WriteString(r.Reasons[0])
b.WriteString(reasons[0])
b.WriteString(".")
} else {
b.WriteString(":\n")
for _, reason := range r.Reasons {
for _, reason := range reasons {
b.WriteString("- ")
b.WriteString(reason)
b.WriteString("\n")
Expand Down
49 changes: 49 additions & 0 deletions src/pkg/stagelabels/human_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -995,3 +995,52 @@ func TestDecisionActionsDoNotReaskARecordedApproval(t *testing.T) {
t.Fatalf("requires_human actions = %q", got)
}
}

// TestDecisionCommentReasonList pins projectbluefin/fsdk-containers#553: a
// route that reaches 085 with no reasons names DecisionReasonUnnamed, never
// "Needs a decision, not a merge:" over an empty list; one reason and
// several reasons render as before.
func TestDecisionCommentReasonList(t *testing.T) {
for _, tc := range []struct {
name string
reasons []string
want string
}{
{name: "zero reasons name the generic cause", want: "\nNeeds a decision, not a merge: the reviewer asked for a human decision.\n\n"},
{name: "one reason is inline", reasons: []string{"the review found: the reviewer marked this change high-risk"}, want: "\nNeeds a decision, not a merge: the review found: the reviewer marked this change high-risk.\n\n"},
{name: "several reasons are a list", reasons: []string{"first", "second"}, want: "\nNeeds a decision, not a merge:\n- first\n- second\n\n\n"},
} {
t.Run(tc.name, func(t *testing.T) {
got := DecisionComment(Route{Stage: NeedsDecision, Reasons: tc.reasons})
if !strings.HasPrefix(got, DecisionCommentMarker+tc.want) {
t.Fatalf("DecisionComment =\n%q\nwant prefix\n%q", got, DecisionCommentMarker+tc.want)
}
if strings.Contains(got, "not a merge:\n\n") {
t.Fatalf("DecisionComment has an empty reason list:\n%s", got)
}
})
}
}

// RequiresHumanReasons is the one wording of a requires_human verdict, shared
// by RouteHuman and the same-head 085 re-park.
func TestRequiresHumanReasons(t *testing.T) {
got := RequiresHumanReasons("0afe7c60b570d5b0", "the reviewer marked this change high-risk", "", []string{" ", "privacy impact unclear"})
want := []string{
"the reviewer swarm returned `requires_human` @0afe7c6",
"the review found: the reviewer marked this change high-risk",
"reviewer summary: privacy impact unclear",
}
if strings.Join(got, "\n") != strings.Join(want, "\n") {
t.Fatalf("RequiresHumanReasons = %q, want %q", got, want)
}
e := readyEvidence()
e.AuthorKind = authorkind.Clanker
e.Verdict = VerdictRequiresHuman
e.DecisionFinding = "the reviewer marked this change high-risk"
e.DecisionQuestion = "ship it?"
r := RouteHuman(e)
if want := RequiresHumanReasons(e.Head, e.DecisionFinding, e.DecisionQuestion, nil); r.Stage != NeedsDecision || strings.Join(r.Reasons, "\n") != strings.Join(want, "\n") {
t.Fatalf("RouteHuman reasons = %q, want %q", r.Reasons, want)
}
}
Loading