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-18872-nudge-then-adopt.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- A contributor PR the hive is going to adopt anyway (author relay offline or unregistered, adoption enabled and unblocked) no longer gets a "back in your court" nudge followed by an adoption note 16-39 minutes later: the nudge is recorded (the adoption clock still runs, the relay still gets its task) but its GitHub comment is withheld, so the author gets one notification, and it is posted if the adoption stops being certain; an online author keeps the nudge and the full grace, and the ladder's immediate-supersede rung fires only for an unreachable author, the same condition. (#18872).
1 change: 1 addition & 0 deletions src/cmd/hive/merge_eligibility.go
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,7 @@ func stageLabelPolicyFunc(cfg *config.Config) func() automerge.StageLabelPolicy
Dwell: stage.DwellOverrides(),
StalledRequireQuiet: stage.Stalled.IsRequireQuiet(),
ContributorNudge: stage.ContributorNudge.IsEnabled(),
NudgeWithholdWhenAdopting: true,
RenudgeInterval: nudgeRepeatAfter(cfg),
CIFailureCooldown: stage.ContributorNudge.EffectiveCIFailureCooldown(),
Adoption: stage.Adoption.IsEnabled(),
Expand Down
15 changes: 15 additions & 0 deletions src/docs/labels-and-control-signals/stage-labels.md
Original file line number Diff line number Diff line change
Expand Up @@ -800,6 +800,21 @@ When a contributor-agent PR goes red the hive does not just relabel it (a human-
(default 6h) is folded into the comment too; after the cooldown it
counts as a fresh nudge. The ledger lives in the stage-label store, so
a restart does not re-nudge.
One outcome per head (hivecommons/hive#18872): a head the hive adopts
anyway gets **no** "back in your court" comment. When the author's relay
is offline or not registered here (live presence is known), adoption is
enabled and nothing blocks it (no hold label, no fork guard, no workflow
path, `maintainer_policy: adopt`), the `AutoAdoption` clock will adopt the
head regardless of what the author does next, so the nudge is only
*recorded* (the clock starts on it, the relay still receives its
`fix-pr` task) and the adoption note is the author's one notification.
An author whose relay is online keeps the nudge and the full online grace
(`contributor_grace_online`); a withheld nudge is posted as soon as the
adoption stops being certain (the relay reconnects, the adoption is held
or blocked). The operator's "Let hive decide" ladder agrees: rung 5
(`contributor-offline`, supersede now) only fires for an author who is not
reachable, the same condition. This follows the documented rule that a
contributor who has gone quiet is superseded now (#13975).
2. Relay contributors (the author has a contributor profile and a live relay
connection) also receive the diagnosis in their relay session as a
`fix-pr` task with `priority: interrupt`. Presence = a relay heartbeat
Expand Down
25 changes: 23 additions & 2 deletions src/pkg/delegatedecision/ladder.go
Original file line number Diff line number Diff line change
Expand Up @@ -202,7 +202,7 @@ func decideLadder(in Input, ref string) (Decision, bool) {

// Rung 4 — return to contributor: their clanker or hive is reachable
// (presence, or the rework-pickup signal of hivecommons/hive#15280).
if in.ContributorOnline || in.ReworkPickedUp {
if in.ContributorReachable() {
fix := fixList(in)
if len(fix) == 0 {
return Decision{}, false
Expand All @@ -222,7 +222,12 @@ func decideLadder(in Input, ref string) (Decision, bool) {
}
skip(RuleReturnToContributor, in.OfflineWording())

// Rung 5 — adopt-supersede, the last resort.
// Rung 5 — adopt-supersede, the last resort. Reaching it means the
// author is NOT reachable (rung 4 returned the PR otherwise), and for
// an unreachable author a "back in your court" nudge asks for work
// they will not get to do: the contributor nudge is withheld under the
// same condition (AdoptsImmediately), so the author's one notification
// is the adoption note (hivecommons/hive#18872).
if in.AdoptionGraceElapsed {
text := "adopt now: the offline grace on " + ref + " has already elapsed; adopt in supersede mode at once, preserving the author's commits and sign-off"
d := Decision{
Expand All @@ -244,6 +249,22 @@ func decideLadder(in Input, ref string) (Decision, bool) {
return Decision{}, false
}

// ContributorReachable reports whether the author's clanker or hive is
// connected or has picked the rework up: the condition under which rung 4
// returns the PR to them and rung 5 never fires.
func (in Input) ContributorReachable() bool { return in.ContributorOnline || in.ReworkPickedUp }

// AdoptsImmediately reports whether the ladder would adopt this head in
// supersede mode right now, without waiting for the grace. The contributor
// nudge and the ladder must agree on one outcome per head
// (hivecommons/hive#18872): a head for which this is true is not nudged
// ("back in your court") only to be adopted minutes later; and a head that is
// given a real chance (ContributorReachable) is never adopted by rung 5.
func AdoptsImmediately(in Input) bool {
d, ok := decideLadder(in, "this PR")
return ok && d.Verdict == VerdictAdoptSupersede
}

// decideAlreadyFixed is rung 1: close as superseded by the merged closer,
// with a courteous note naming it. A paused repo or a person's PR gets a
// recommendation instead of a write.
Expand Down
42 changes: 42 additions & 0 deletions src/pkg/delegatedecision/ladder_nudge_agreement_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
package delegatedecision

import "testing"

// hivecommons/hive#18872: the ladder and the contributor nudge agree on one
// outcome per head. Rung 5 fires exactly when the author is unreachable
// (the nudge is withheld under that condition) and never for a reachable
// author (who keeps the nudge and the real grace).
func TestLadderAndNudgeAgree(t *testing.T) {
base := Input{Repo: "hivecommons/hive", Kind: KindPR, Number: 18561, AuthorTooling: AuthorToolingClanker}
patterns := []struct {
name string
mut func(*Input)
}{
{"conflicting", func(i *Input) { i.Conflicting = true; i.CIGreen = true }},
{"check-failing", func(i *Input) { i.CIGreen = false }},
{"dco-missing", func(i *Input) { i.CIGreen = true; i.DCOMissing = true }},
{"adoption-stalled", func(i *Input) { i.CIGreen = true; i.AdoptionStalled = true }},
}
for _, p := range patterns {
t.Run(p.name+"/unreachable", func(t *testing.T) {
in := with(base, p.mut)
if in.ContributorReachable() || !AdoptsImmediately(in) {
t.Fatalf("an unreachable author's head is superseded now (reachable=%v)", in.ContributorReachable())
}
})
for _, reach := range []struct {
name string
mut func(*Input)
}{
{"online", func(i *Input) { i.ContributorOnline = true }},
{"rework-picked-up", func(i *Input) { i.ReworkPickedUp = true }},
} {
t.Run(p.name+"/"+reach.name, func(t *testing.T) {
in := with(with(base, p.mut), reach.mut)
if !in.ContributorReachable() || AdoptsImmediately(in) {
t.Fatalf("a reachable author gets a real chance, not rung 5")
}
})
}
}
}
47 changes: 43 additions & 4 deletions src/pkg/github/automerge/automerge_contributor_nudge.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import (

gh "github.com/google/go-github/v72/github"
"github.com/hivecommons/hive/pkg/advisory"
"github.com/hivecommons/hive/pkg/config"
"github.com/hivecommons/hive/pkg/prstatus"
"github.com/hivecommons/hive/pkg/stagelabels"
)
Expand Down Expand Up @@ -377,9 +378,36 @@ func ciNudgeDue(rec stagelabels.Record, head string, checks []string, repeatAfte
return 1, true
}

// adoptionBound reports whether the hive is going to adopt this head
// whatever the author does next, so one notification (the adoption note)
// replaces the nudge (hivecommons/hive#18872). It is the nudge-side twin of
// delegatedecision.AdoptsImmediately: an author whose relay is online (or
// who has picked the rework up) is given the real grace and is nudged; an
// author with no reachable relay (registered but offline, or not registered
// here) is adopted on the AutoAdoption clock, which only needs the nudge to
// be recorded, not posted. Anything that could keep the adoption from
// happening (no presence source, a hold label, a fork guard, a workflow
// path, a person's PR, a maintainer policy other than adopt, a recorded
// block) keeps the nudge, so no author is left with no word at all.
func adoptionBound(rec stagelabels.Record, obs stageObservation, policy StageLabelPolicy, presence ContributorPresence, hasPresence bool) bool {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Open question: the doc comment says reachability includes an author who picked the rework up (as delegatedecision.ContributorReachable does, ladder.go:255), but this function only checks presence.Registered && presence.Online. AdoptsImmediately is called only from its own test, so nothing keeps the two in step. If a claimed fix-pr task keeps AutoAdoption from adopting, that author's nudge is withheld wrongly; if not, drop the wording.

if !policy.NudgeWithholdWhenAdopting || !policy.Adoption || !hasPresence || (presence.Registered && presence.Online) {
return false
}
if obs.HeadSHA == "" || rec.AdoptionBlocked(obs.HeadSHA) != "" || adoptionBlocked(obs.Labels) != "" || adoptionForkGuardOnly(obs) {
return false
}
if policy.maintainerPolicy() != config.AdoptionMaintainerPolicyAdopt || personAuthored(obs, policy) {
return false
}
return !strings.Contains(nonEmpty(obs.Reason, obs.LaneReason), contributorLaneReasonWorkflowPath)
}

// nudgeContributor runs the stage-072 nudge for one observation. It returns
// the number of GitHub comments posted.
func (c *Engine) nudgeContributor(ctx context.Context, store *stagelabels.Store, key string, obs stageObservation, policy StageLabelPolicy, now time.Time) (int, error) {
// the number of GitHub comments posted. When the hive is going to adopt the
// head anyway (adoptionBound) the nudge is recorded, so the adoption clock
// runs, and dispatched to the relay, but the GitHub comment is withheld
// (hivecommons/hive#18872); it is posted later if adoption does not happen.
func (c *Engine) nudgeContributor(ctx context.Context, store *stagelabels.Store, key string, obs stageObservation, policy StageLabelPolicy, presence ContributorPresence, hasPresence bool, now time.Time) (int, error) {
rec, ok := store.Get(key)
if !ok || obs.Author == "" {
return 0, nil
Expand Down Expand Up @@ -410,8 +438,14 @@ func (c *Engine) nudgeContributor(ctx context.Context, store *stagelabels.Store,
} else {
ordinal, due = nudgeDue(rec, obs.HeadSHA, obs.Reason, policy.RenudgeInterval, now)
}
bound := adoptionBound(rec, obs, policy, presence, hasPresence)
if !due {
return 0, nil
// A withheld nudge is owed to the author as soon as the adoption
// that was to speak for this head is no longer certain.
if bound || rec.NudgeWithheldHead == "" || rec.NudgeWithheldHead != obs.HeadSHA {
return 0, nil
}
ordinal = 0
}
// A head-only rewrite (ordinal 0) keeps the class's recorded count in
// the marker; the author pushed, so it is not the stall reminder.
Expand Down Expand Up @@ -447,13 +481,18 @@ func (c *Engine) nudgeContributor(ctx context.Context, store *stagelabels.Store,
// is the interrupt.
posted := 0
if existing := c.findOwnEntryComment(ctx, obs, ContributorNudgeMarkerPrefix); existing != nil {
store.NoteNudgeWithheld(key, "")
if existing.GetBody() != body {
if _, _, err := c.gh.Issues.EditComment(ctx, obs.Owner, obs.Repo, existing.GetID(), &gh.IssueComment{Body: gh.Ptr(body)}); err != nil { // writeback:gated
c.warn("stage labels: contributor nudge edit failed", "repo", obs.Display, "pr", obs.Number, "error", err)
return 0, err
}
}
} else if bound {
store.NoteNudgeWithheld(key, obs.HeadSHA)
c.info("stage labels: contributor nudge withheld, the hive adopts this head anyway; the adoption note is the one notification", "repo", obs.Display, "pr", obs.Number, "author", obs.Author, "head", obs.HeadSHA, "reason", obs.Reason, "registered", presence.Registered)
} else {
store.NoteNudgeWithheld(key, "")
if _, _, err := c.gh.Issues.CreateComment(ctx, obs.Owner, obs.Repo, obs.Number, &gh.IssueComment{Body: gh.Ptr(body)}); err != nil {
c.warn("stage labels: contributor nudge failed", "repo", obs.Display, "pr", obs.Number, "error", err)
return 0, err
Expand All @@ -468,7 +507,7 @@ func (c *Engine) nudgeContributor(ctx context.Context, store *stagelabels.Store,
if ciFailure {
store.MarkNudgedCIFailure(key, checks, obs.HeadSHA, nonEmpty(out.Mode, "comment"), attempt, ordinal == 1, now)
}
c.info("stage labels: contributor nudged", "repo", obs.Display, "pr", obs.Number, "author", obs.Author, "head", obs.HeadSHA, "nudge", ordinal, "posted", posted == 1, "mode", nonEmpty(out.Mode, "comment"), "online", out.Online, "queue_depth", out.QueueDepth, "relay_failed", out.RelayFailed, "reason", obs.Reason)
c.info("stage labels: contributor nudged", "repo", obs.Display, "pr", obs.Number, "author", obs.Author, "head", obs.HeadSHA, "nudge", ordinal, "posted", posted == 1, "withheld", bound && posted == 0, "mode", nonEmpty(out.Mode, "comment"), "online", out.Online, "queue_depth", out.QueueDepth, "relay_failed", out.RelayFailed, "reason", obs.Reason)
return posted, nil
}

Expand Down
153 changes: 153 additions & 0 deletions src/pkg/github/automerge/automerge_nudge_withhold_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,153 @@
package automerge

import (
"testing"
"time"

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

// hivecommons/hive#18872: a contributor got "this PR is back in your court"
// and 16-39 minutes later the hive adopted the same PR. The nudge and the
// adoption now agree on one outcome per head: a head the hive adopts anyway
// (author relay offline or unregistered) is nudged on the record only, so
// the adoption clock runs and the adoption note is the one notification; a
// head with a real chance (relay online) keeps its nudge and is not adopted
// before the grace.

// withholdPatterns are the four pairs observed on the hive's spoke:
// #18561 contributor-lane, #18628 fork-not-editable, #18514 check-failing,
// #18510 conflicting.
var withholdPatterns = []struct{ name, reason string }{
{"contributor-lane", contributorLaneReasonChangesRequested},
{"fork-not-editable", autoMergeReasonForkNotEditable},
{"check-failing", "required-check-failing:changelog-fragment-guard"},
{"conflicting", "conflicting"},
}

var withholdLabels = []string{"stage/072-returned-to-contributor", "role/contributor", "author/clanker"}

func withholdPolicy() StageLabelPolicy {
p := adoptPolicy()
p.NudgeWithholdWhenAdopting = true
return p
}

func TestNudgeWithheldWhenHiveAdoptsAnyway(t *testing.T) {
for _, pat := range withholdPatterns {
for _, registered := range []bool{true, false} {
name := pat.name + "/unregistered"
if registered {
name = pat.name + "/offline"
}
t.Run(name, func(t *testing.T) {
h, done := newAdoptHarness(t, ContributorNudgeOutcome{Mode: "queued"}, withholdPolicy())
defer done()
start := h.clock.at
h.sink.presence = &ContributorPresence{Registered: registered}
h.observe(adoptPR(7, "aaa"), pat.reason)
// Invariant 1: no nudge comment for a head that is adopted anyway.
if got := nudgeComments(h.api); len(got) != 0 {
t.Fatalf("nudge posted for a head the hive adopts anyway: %v", got)
}
// The nudge is recorded: the adoption clock is running on it.
rec, ok := h.e.stageStoreOrShared().Get(stageKey("acme", "widget", 7))
if !ok || rec.NudgeHead != "aaa" || rec.NudgeCount == 0 || rec.NudgeWithheldHead != "aaa" {
t.Fatalf("withheld nudge not recorded: %+v", rec)
}
// The adoption follows on the AutoAdoption clock, with its note.
h.api.reset()
h.clock.at = start.Add(16 * time.Minute)
h.observe(adoptPR(7, "aaa", withholdLabels...), pat.reason)
if len(adoptionComments(h.api)) != 1 {
t.Fatalf("no adoption note at +16m: %v", h.api.comments)
}
if got := nudgeComments(h.api); len(got) != 0 {
t.Fatalf("a nudge was posted next to the adoption: %v", got)
}
})
}
}
}

func TestNudgeKeptAndNoEarlyAdoptionWhenAuthorHasARealChance(t *testing.T) {
for _, pat := range withholdPatterns {
t.Run(pat.name, func(t *testing.T) {
h, done := newAdoptHarness(t, ContributorNudgeOutcome{Mode: "queued"}, withholdPolicy())
defer done()
start := h.clock.at
h.sink.presence = &ContributorPresence{Registered: true, Online: true}
h.observe(adoptPR(7, "aaa"), pat.reason)
if len(nudgeComments(h.api)) != 1 {
t.Fatalf("an online author is nudged: %v", h.api.comments)
}
// Invariant 2: not adopted before the online grace.
for _, at := range []time.Duration{16 * time.Minute, 31 * time.Minute, time.Hour} {
h.api.reset()
h.clock.at = start.Add(at)
h.observe(adoptPR(7, "aaa", withholdLabels...), pat.reason)
if len(adoptionComments(h.api)) != 0 || len(h.adopt.pulls) != 0 {
t.Fatalf("adopted at +%v before the grace: %v", at, h.api.comments)
}
}
})
}
}

func TestWithheldNudgeIsPostedWhenTheAuthorReappears(t *testing.T) {
h, done := newAdoptHarness(t, ContributorNudgeOutcome{Mode: "queued"}, withholdPolicy())
defer done()
start := h.clock.at
h.sink.presence = &ContributorPresence{Registered: true}
h.observe(adoptPR(7, "aaa"), "conflicting")
if len(nudgeComments(h.api)) != 0 {
t.Fatalf("nudge should be withheld: %v", h.api.comments)
}
// The relay reconnects before the adoption is due: a real chance now.
h.sink.presence = &ContributorPresence{Registered: true, Online: true}
h.clock.at = start.Add(5 * time.Minute)
h.observe(adoptPR(7, "aaa", withholdLabels...), "conflicting")
if len(nudgeComments(h.api)) != 1 {
t.Fatalf("the withheld nudge is owed once the author is reachable: %v", h.api.comments)
}
rec, _ := h.e.stageStoreOrShared().Get(stageKey("acme", "widget", 7))
if rec.NudgeWithheldHead != "" {
t.Fatalf("withheld mark not cleared: %+v", rec)
}
}

func TestNudgeNotWithheldWithoutCertainAdoption(t *testing.T) {
t.Run("policy flag off", func(t *testing.T) {
h, done := newAdoptHarness(t, ContributorNudgeOutcome{Mode: "queued"}, adoptPolicy())
defer done()
h.sink.presence = &ContributorPresence{Registered: true}
h.observe(adoptPR(7, "aaa"), "conflicting")
if len(nudgeComments(h.api)) != 1 {
t.Fatalf("withholding is off by default in the engine: %v", h.api.comments)
}
})
t.Run("no presence source", func(t *testing.T) {
fake := &fakeNudgeSink{outcome: ContributorNudgeOutcome{Mode: "comment"}}
h, done := newAdoptHarnessWith(t, fake, nudgeOnlySink{fake}, withholdPolicy())
defer done()
h.observe(adoptPR(7, "aaa"), "conflicting")
if len(nudgeComments(h.api)) != 1 {
t.Fatalf("without presence the adoption is not certain: %v", h.api.comments)
}
})
t.Run("adoption disabled", func(t *testing.T) {
p := withholdPolicy()
p.Adoption = false
rec := stagelabels.Record{}
if adoptionBound(rec, stageObservation{HeadSHA: "aaa"}, p, ContributorPresence{Registered: true}, true) {
t.Fatal("adoption off cannot be certain")
}
})
t.Run("maintainer policy ask", func(t *testing.T) {
p := withholdPolicy()
p.AdoptionMaintainerPolicy = "ask"
if adoptionBound(stagelabels.Record{}, stageObservation{HeadSHA: "aaa"}, p, ContributorPresence{Registered: true}, true) {
t.Fatal("a held adoption cannot be certain")
}
})
}
7 changes: 6 additions & 1 deletion src/pkg/github/automerge/automerge_stage_labels.go
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,11 @@ type StageLabelPolicy struct {
// Every other contributor-lane gate still applies; the head must be
// exactly the one the stage store records as adopted/pushed by the hive.
AdoptionAutoMerge bool
// NudgeWithholdWhenAdopting withholds the nudge comment for a head the
// hive adopts anyway (always on in production, see stageLabelPolicyFunc;
// off in the zero policy so older tests keep their nudge;
// hivecommons/hive#18872).
NudgeWithholdWhenAdopting bool
// AdoptionMaintainerPolicy is governor.labels.stage.adoption.maintainer_policy
// (config.AdoptionMaintainerPolicy*): what adoption does when the PR
// author holds admin or maintain on the repository. "" reads as the
Expand Down Expand Up @@ -1429,7 +1434,7 @@ func (c *Engine) ApplyStageLabels(ctx context.Context) (StageLabelResult, error)
}
if kind == authorkind.Clanker {
if policy.ContributorNudge && !adoptionRetry {
n, err := c.nudgeContributor(ctx, store, key, obs, policy, now)
n, err := c.nudgeContributor(ctx, store, key, obs, policy, presence, hasPresence, now)
result.Comments += n
if err != nil && firstErr == nil {
firstErr = err
Expand Down
Loading
Loading