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
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Notifications: in `github.notifications.mode: quiet` (the default) three more notes stop posting comments of their own and become `hive:status` card sections, edited in place: the review Follow-ups checklist (`review-followups`, collapsible, ticked entries kept), the 090 ready-for-human-merge entry when the author's trust tier is the only objection (`stage-ready`), and the issue-side stage note naming the PR that covers the issue (`issue-pr-link`). Every 085 needs-decision entry and a held or manual-merge 090 still post a notifying comment; `mode: normal` is unchanged (hivecommons/hive#18606).
8 changes: 7 additions & 1 deletion src/docs/notifications.md
Original file line number Diff line number Diff line change
Expand Up @@ -487,10 +487,12 @@ without a class. Review submissions and review requests are always counted as
| `automerge.(*engineStatusForge).CreateComment` | `status` | passthrough wrapper shared by normal-mode stage notes and the quiet-mode status-comment forge under `prstatus.Write`; attributed to its caller |
| `github.(*clientStatusForge).CreateComment` | `status` | passthrough wrapper (status-comment forge under `prstatus.Write`); attributed to its caller |
| `github.(*Client).PostIssueNote` | `status` | passthrough wrapper (issue status card, `attention_pilot`); attributed to its caller |
| `github.(*Client).PostInformationalIssueNote` | `status` | passthrough wrapper (issue status card in quiet mode or under `attention_pilot`, for notes nobody acts on); attributed to its caller |
| `github.(*Client).closeDecomposedParent` | `status` | |
| `github.(*Client).closeIssueForMergedPRClaimWithIssue` | `status` | |
| `github.(*Client).closeSupersededPRDecision` | `status` | |
| `github.(*Client).fileReviewBacklog` | `status` | |
| `github.(*Client).foldReviewFollowUps` | `status` | review Follow-ups checklist folded into the PR status card (quiet mode) |
| `github.(*Client).foldSentinelNotice` | `status` | informational sentinel notice folded into the PR status card (quiet mode); a blocking alert is never folded |
| `github.(*Client).joinFleetReportIssue` | `status` | |
| `github.(*Client).markInProgressStarted` | `status` | |
Expand Down Expand Up @@ -578,7 +580,11 @@ Quiet mode (`github.notifications.mode: quiet`) folds the hive's PR
bookkeeping into one edited `hive:status` comment (including the auto-merge
note, under the `auto-merge` section: in `normal` mode it stays its own
comment, and a merge blocked on a person still gets its 085 / 090 entry
comment, hivecommons/hive#18452) but leaves issue notes as
comment, hivecommons/hive#18452; the review Follow-ups checklist, under
`review-followups`, and a trust-only 090 entry, under `stage-ready`, while a
held or manual-merge 090 and every 085 stay comments, hivecommons/hive#18606)
but leaves issue notes (except the informational `issue-pr-link` stage note)
as
comments of their own, so one issue lifecycle (partial merge, remainder,
close) could still email its watchers several times. With the pilot on, the
issue gets the same card, written through the same single status writer
Expand Down
13 changes: 10 additions & 3 deletions src/docs/operator-reference/sweeps-and-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -552,9 +552,16 @@ not what it records:
Hive trusted-author auto-merge …" or "merged by Hive on behalf of …") is
the card's `auto-merge` section too, with its @-mentions neutralised, so
a merge no longer emails the author and every watcher; in `normal` it is
still its own comment. A merge that waits on a person (the 085
needs-decision and 090 ready-for-human-merge entry comments) still posts
a comment of its own.
still its own comment. The review Follow-ups checklist (findings held
below `review.backlog.min_severity`) is the card's collapsible
`review-followups` section, ticks kept across passes (a PR that already
has the old Follow-ups comment keeps editing that one), and a 090
ready-for-human-merge entry whose only objection is the author's trust
tier is the card's `stage-ready` line (hivecommons/hive#18606). A merge
that waits on a specific step from a person (every 085 needs-decision
entry, and a held or manual-merge 090) still posts a comment of its own.
On the issue side the stage note naming the covering PR
(`issue-pr-link`) is a section of the issue's card in quiet mode too.
- **No "no findings" reviews.** A reviewer whose whole body is the clean
acknowledgement — or whose body says it has no findings while its verdict
report approves with an empty findings list, as the plain `reviewer`
Expand Down
45 changes: 44 additions & 1 deletion src/pkg/github/automerge/automerge_stage_human.go
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ import (
"github.com/hivecommons/hive/pkg/authorkind"
hgithub "github.com/hivecommons/hive/pkg/github"
"github.com/hivecommons/hive/pkg/oktotest"
"github.com/hivecommons/hive/pkg/prstatus"
"github.com/hivecommons/hive/pkg/review"
"github.com/hivecommons/hive/pkg/stageengine"
"github.com/hivecommons/hive/pkg/stageengine/prstage"
Expand Down Expand Up @@ -701,7 +702,27 @@ func (c *Engine) postHumanEntry(ctx context.Context, store *stagelabels.Store, k
// (hivecommons/hive#16433): a later head or cause rewrites the hive's
// existing 085 / 090 comment with an "updated" line instead of posting
// another copy, which emailed everyone again to say the same thing.
if existing := c.findOwnEntryComment(ctx, obs, stagelabels.EntryCommentMarker(route.Stage)); existing != nil {
existing := c.findOwnEntryComment(ctx, obs, stagelabels.EntryCommentMarker(route.Stage))
if route.Stage == stagelabels.ReadyForHumanMerge && existing == nil && c.stagePolicy().QuietNotifications {
if readyEntryFolds(route) {
n, err := c.writeStatusSectionWith(ctx, obs.Owner, obs.Repo, obs.Number, prstatus.KeyStageReady, readyCardSection(body), prstatus.Write)
if err != nil {
c.warn("stage labels: ready line on the status card failed", "repo", obs.Display, "pr", obs.Number, "error", err)
return 0, err
}
store.MarkEntryCommentedCause(key, obs.HeadSHA, cause)
store.MarkEntryCommentedDecisionKey(key, decisionKey)
c.info("stage labels: ready entry folded into the status card", "repo", obs.Display, "pr", obs.Number)
return n, nil
}
// A held or manual-merge 090 is a person's step and posts its own
// comment below; the plain "ready" line it replaces is dropped so
// the card never reads ready next to the hold. Best effort.
if _, err := c.writeStatusSectionWith(ctx, obs.Owner, obs.Repo, obs.Number, prstatus.KeyStageReady, "", prstatus.Write); err != nil {
c.warn("stage labels: clearing the ready line on the status card failed", "repo", obs.Display, "pr", obs.Number, "error", err)
}
}
if existing != nil {
updated := stagelabels.EntryCommentUpdated(body, c.now())
// Rewrites the comment the gate admitted when it was posted; an edit notifies nobody.
if _, _, err := c.gh.Issues.EditComment(ctx, obs.Owner, obs.Repo, existing.GetID(), &gh.IssueComment{Body: gh.Ptr(updated)}); err != nil { // writeback:gated
Expand All @@ -723,6 +744,28 @@ func (c *Engine) postHumanEntry(ctx context.Context, store *stagelabels.Store, k
return 1, nil
}

// readyCardMarker stamps the 090 status-card line. It deliberately is not
// stagelabels.ReadyCommentMarker: findOwnEntryComment would read a card
// carrying that marker as the entry comment and overwrite the whole card.
const readyCardMarker = "<!-- hive:stage-ready-card -->"

// readyEntryFolds reports whether a 090 entry is the plain "ready for a
// human merge" note that quiet mode writes as the stage-ready line of the
// PR's hive:status card (hivecommons/hive#18606): the PR's only objection is
// the author's trust tier and the stage/090 label and tracker already show
// it. A held head (a sentinel alert or hold label, route.Gates) or an
// approved manual-merge route asks a person for a specific step, so it
// keeps its own notifying comment, as does every 085 entry.
func readyEntryFolds(route stagelabels.Route) bool {
return route.Stage == stagelabels.ReadyForHumanMerge && !route.ManualMerge && len(route.Gates) == 0
}

// readyCardSection is body (a stagelabels.ReadyComment) as a status-card
// section: the same text under readyCardMarker.
func readyCardSection(body string) string {
return strings.Replace(body, stagelabels.ReadyCommentMarker, readyCardMarker, 1)
}

// findOwnEntryComment returns the hive's existing entry comment carrying
// marker on the PR, or nil. Only a comment the hive's App login wrote
// counts: anyone can type the marker, and the hive must never edit a
Expand Down
123 changes: 123 additions & 0 deletions src/pkg/github/automerge/automerge_stage_ready_status_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
package automerge

// Tests for the 090 ready-for-human-merge entry's quiet-mode delivery
// (hivecommons/hive#18606): a PR whose only objection is the author's trust
// tier gets a stage-ready line on its hive:status card instead of a comment
// of its own; a held 090 (sentinel alert, hold label) still posts its own
// notifying comment, as does every 085 needs-decision entry.

import (
"context"
"strings"
"testing"
"time"

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

func quietReadyEngine(t *testing.T) (*stageAPI, func(reason string, labels ...string), *stagelabels.Store) {
t.Helper()
api, closeAPI := seededStageAPI(t)
t.Cleanup(closeAPI)
api.statefulComments = true
api.posted = map[int][]map[string]any{9: {{
"id": int64(900),
"body": prstatus.Upsert("", prstatus.KeyStageStalled, "<!-- hive:stage-stalled --> waiting"),
"user": map[string]any{"login": testHiveAppBotLogin},
}}}
clock := &contributorLaneClock{at: time.Date(2026, 11, 16, 12, 0, 0, 0, time.UTC)}
verdict := &ContributorLaneVerdict{Configured: true, Approved: true, Verdict: "approve"}
e, store := humanStageEngine(t, api.url, clock, verdict, 0)
e.stageLabelPolicy = func() StageLabelPolicy { return StageLabelPolicy{Enabled: true, QuietNotifications: true} }
sweep := func(reason string, labels ...string) {
t.Helper()
api.reset()
e.recordStage(stageLaneTrusted, "acme/widget", "acme", "widget", stagePR(9, labels...), "untrusted-author-role", false, nil)
e.recordStage(stageLaneContributor, "acme/widget", "acme", "widget", stagePR(9, labels...), reason, false, nil)
e.noteStageRole("acme", "widget", 9, stagelabels.RoleContributor)
if _, err := e.ApplyStageLabels(context.Background()); err != nil {
t.Fatal(err)
}
}
return api, sweep, store
}

func cardOf(t *testing.T, api *stageAPI) string {
t.Helper()
api.mu.Lock()
defer api.mu.Unlock()
for _, c := range api.posted[9] {
if body, _ := c["body"].(string); prstatus.IsStatusComment(body) {
return body
}
}
t.Fatal("PR 9 has no status card")
return ""
}

func TestReadyEntryQuietFoldsIntoStatusCard(t *testing.T) {
api, sweep, store := quietReadyEngine(t)
sweep(contributorLaneReasonClaimTier, "role/contributor", "author/human", "stage/050-review-pending")
if got := stageOf(t, store, 9); got != stagelabels.ReadyForHumanMerge {
t.Fatalf("stage=%v want 090", got)
}
if len(api.comments) != 0 {
t.Fatalf("quiet 090 posted %d comments, want none: %q", len(api.comments), api.comments)
}
card := cardOf(t, api)
if _, ok := prstatus.Get(card, prstatus.KeyStageStalled); !ok {
t.Fatalf("existing card section lost:\n%s", card)
}
section, ok := prstatus.Get(card, prstatus.KeyStageReady)
if !ok || !strings.Contains(section, "Ready for a human merge: verdict approved `sha`") || !strings.Contains(section, "Blocked only by `role/contributor`") || !strings.Contains(section, "`/lgtm` `/approve`") {
t.Fatalf("stage-ready section = %q (found %v)", section, ok)
}
if strings.Contains(card, stagelabels.ReadyCommentMarker) {
t.Fatalf("the card must not carry the entry-comment marker (the entry upsert would overwrite it):\n%s", card)
}

// Same head and cause again: nothing is written.
edits := len(api.commentEdits)
sweep(contributorLaneReasonClaimTier, "role/contributor", "author/human", "stage/090-ready-for-human-merge")
if len(api.comments) != 0 || len(api.commentEdits) != edits {
t.Fatalf("re-sweep wrote: comments=%q edits=%d→%d", api.comments, edits, len(api.commentEdits))
}
}

// A held 090 asks a person to clear the gate, so it still posts its own
// comment in quiet mode, and the plain ready line is dropped from the card.
func TestReadyEntryQuietHeldStillComments(t *testing.T) {
api, sweep, _ := quietReadyEngine(t)
sweep(contributorLaneReasonClaimTier, "role/contributor", "author/human", "stage/050-review-pending")
if _, ok := prstatus.Get(cardOf(t, api), prstatus.KeyStageReady); !ok {
t.Fatal("setup: no ready line on the card")
}
sweep(contributorLaneReasonSentinelBlocked, "role/contributor", "author/human", "stage/090-ready-for-human-merge", "sentinel-alert")
if len(api.comments) != 1 || !strings.HasPrefix(api.comments[0], stagelabels.ReadyCommentMarker) || !strings.Contains(api.comments[0], "Held: a sentinel alert is open on this PR.") {
t.Fatalf("held 090 must post its own comment: %q", api.comments)
}
if prstatus.IsStatusComment(api.comments[0]) {
t.Fatalf("held comment is the card: %q", api.comments[0])
}
if section, ok := prstatus.Get(cardOf(t, api), prstatus.KeyStageReady); ok {
t.Fatalf("stale ready line kept next to the hold: %q", section)
}
}

func TestReadyEntryFolds(t *testing.T) {
for _, tc := range []struct {
name string
route stagelabels.Route
want bool
}{
{"plain ready", stagelabels.Route{Stage: stagelabels.ReadyForHumanMerge}, true},
{"held ready", stagelabels.Route{Stage: stagelabels.ReadyForHumanMerge, Gates: []string{"a sentinel alert is open on this PR"}}, false},
{"manual merge", stagelabels.Route{Stage: stagelabels.ReadyForHumanMerge, ManualMerge: true}, false},
{"needs decision", stagelabels.Route{Stage: stagelabels.NeedsDecision}, false},
} {
if got := readyEntryFolds(tc.route); got != tc.want {
t.Errorf("%s: readyEntryFolds=%v want %v", tc.name, got, tc.want)
}
}
}
2 changes: 1 addition & 1 deletion src/pkg/github/issue_stage_labels.go
Original file line number Diff line number Diff line change
Expand Up @@ -918,7 +918,7 @@ func ensureIssueStagePRLink(ctx context.Context, client *Client, in IssueStageIn
if !ok || rec.EntryCommented {
return false, false, false
}
if _, err := client.PostIssueNote(ctx, in.Repo, in.Number, prstatus.KeyIssuePRLink, link.StageComment, func(ctx context.Context) error {
if _, err := client.PostInformationalIssueNote(ctx, in.Repo, in.Number, prstatus.KeyIssuePRLink, link.StageComment, func(ctx context.Context) error {
return client.CreateIssueComment(ctx, in.Repo, in.Number, link.StageComment)
}); err != nil {
owner, name := client.splitRepo(in.Repo)
Expand Down
21 changes: 21 additions & 0 deletions src/pkg/github/issue_status_card.go
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,27 @@ func (c *Client) PostIssueNote(ctx context.Context, repo string, number int, key
return created, err
}

// PostInformationalIssueNote is PostIssueNote for a note nobody has to act
// on, such as the stage note naming the PR that covers the issue
// (prstatus.KeyIssuePRLink, hivecommons/hive#18606): it becomes a section of
// the issue's status card under the attention pilot or in
// github.notifications.mode: quiet (the default), and runs legacy only in
// mode normal with the pilot off. Reports whether a new comment was
// created.
func (c *Client) PostInformationalIssueNote(ctx context.Context, repo string, number int, key, body string, legacy func(context.Context) error) (bool, error) {
if c == nil {
return false, ErrNoGitHubClient
}
if !c.attentionPilot() && !c.notificationsQuiet() {
return true, legacy(ctx)
}
created, err := c.UpsertPRStatusSection(ctx, repo, number, key, body)
if err == nil && !created {
c.noteCommentSuppressed()
}
return created, err
}

// PostIssueAttention delivers a newly required action (cause names it, e.g.
// the PR whose merge awaits confirmation). With the attention pilot off it
// runs legacy. With it on the action is recorded on the status card and
Expand Down
51 changes: 51 additions & 0 deletions src/pkg/github/issue_status_card_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -241,3 +241,54 @@ func TestIssueStatusCardAttentionGateRefusalRetries(t *testing.T) {
t.Fatalf("repeat: posted=%v err=%v creates=%d", posted, err, s.creates)
}
}

// The PR-link stage note names the PR covering the issue; nobody has to
// act on it, so in github.notifications.mode: quiet it is the issue card's
// issue-pr-link section even with the attention pilot off, and an issue
// that already has a card gets no new comment (hivecommons/hive#18606).
// Mode normal with the pilot off keeps the legacy comment.
func TestInformationalIssueNoteFoldsInQuietMode(t *testing.T) {
ctx := context.Background()
link := issueStagePRLinkComment("https://github.com/o/r/pull/42", 42, "Partial work.")

s := &statusCommentServer{}
c := testClient(t, s.start(t).URL)
c.SetAppBotLogin("hive-app[bot]")
c.SetNotificationsQuiet(func() bool { return true })
noLegacy := func(context.Context) error {
t.Error("legacy write ran in quiet mode")
return nil
}
if _, err := c.UpsertPRStatusSection(ctx, "o/r", 5, prstatus.KeyStageRegressed, "stage regressed"); err != nil {
t.Fatal(err)
}
if s.creates != 1 {
t.Fatalf("setup: creates=%d, want the card", s.creates)
}
created, err := c.PostInformationalIssueNote(ctx, "o/r", 5, prstatus.KeyIssuePRLink, link, noLegacy)
if err != nil || created {
t.Fatalf("created=%v err=%v, want an in-place edit", created, err)
}
if s.creates != 1 || len(s.comments) != 1 {
t.Fatalf("creates=%d comments=%d, want no new comment", s.creates, len(s.comments))
}
body, _ := s.comments[0]["body"].(string)
section, ok := prstatus.Get(body, prstatus.KeyIssuePRLink)
if !ok || !strings.Contains(section, "<!-- hive:issue-stage-pr-link pr=42 -->") || !strings.Contains(section, "PR #42 covers this issue: https://github.com/o/r/pull/42") {
t.Fatalf("pr-link section = %q (found %v)", section, ok)
}

normal := &statusCommentServer{}
n := testClient(t, normal.start(t).URL)
n.SetNotificationsQuiet(func() bool { return false })
legacyCalls := 0
if _, err := n.PostInformationalIssueNote(ctx, "o/r", 5, prstatus.KeyIssuePRLink, link, func(ctx context.Context) error {
legacyCalls++
return n.CreateIssueComment(ctx, "o/r", 5, link)
}); err != nil {
t.Fatal(err)
}
if legacyCalls != 1 || normal.creates != 1 {
t.Fatalf("normal mode: legacy=%d creates=%d, want the comment of its own", legacyCalls, normal.creates)
}
}
2 changes: 2 additions & 0 deletions src/pkg/github/notification_write_sites.go
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@ var notificationWriteSites = map[string]NotificationWriteSite{
"github.(*Client).EditIssueMarkerComment": {Class: NotificationClassStatus, Passthrough: true},
"github.(*clientStatusForge).CreateComment": {Class: NotificationClassStatus, Passthrough: true},
"github.(*Client).PostIssueNote": {Class: NotificationClassStatus, Passthrough: true},
"github.(*Client).PostInformationalIssueNote": {Class: NotificationClassStatus, Passthrough: true},
"github.(*Client).foldReviewFollowUps": {Class: NotificationClassStatus},
"automerge.(*engineStatusForge).CreateComment": {Class: NotificationClassStatus, Passthrough: true},

// status: bookkeeping readable on demand.
Expand Down
15 changes: 15 additions & 0 deletions src/pkg/github/pr_status_comment.go
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,21 @@ func (c *Client) UpsertPRStatusSection(ctx context.Context, repo string, number
return res.Created, err
}

// UpsertPRStatusSectionFunc is UpsertPRStatusSection for a section whose
// text is merged with what it already says (prstatus.WriteFunc): render
// receives the section's current body ("" when none) and is re-run on every
// compare-and-retry read, so an edit a person made in between survives.
// Reports whether a comment was created.
func (c *Client) UpsertPRStatusSectionFunc(ctx context.Context, repo string, number int, key string, render func(previous string) string) (bool, error) {
if c == nil {
return false, ErrNoGitHubClient
}
owner, repoName := c.splitRepo(repo)
f := &clientStatusForge{c: c, owner: owner, repo: repoName, number: number}
res, err := prstatus.WriteFunc(ctx, f, prstatus.ItemKey(owner+"/"+repoName, number), key, render)
return res.Created, err
}

// ownStatusCommentLogin reports whether login is exactly this hive's App bot
// login. Any other account, including another bot, is not the owner, and an
// unknown App login fails closed so nothing is ever edited or deleted.
Expand Down
Loading
Loading