Skip to content

📖 docs: explain webhook claim ledger and pending stage recovery - #14980

Closed
hivecommons-hive[bot] wants to merge 2 commits into
v5from
hive/adopt-14975
Closed

hivecommons-hive[bot] wants to merge 2 commits into
v5from
hive/adopt-14975

Conversation

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Supersedes #14975 (adopted after CI went red and the contributor was unavailable; original commits by @thatguywob preserved).

Closes #14972

This branch is #14975's head de64cb1ad5bf as pushed by @thatguywob (fork thatguywob/hive), unchanged. Last lane reason on the original: contributor-lane:decision-requested.

Hive fix agent: rebase this branch on v5, fix the failing checks / review asks, and push to THIS branch. Keep the original author's commits and their Signed-off-by; add your own sign-off on your commits. Do not open another PR.

Document pull_request claim writes, their snapshot and stage effects, and the merge trigger and ledger backfill proposed in #14971.

Hive-Run: #14972
Hive-Plan: docs-currency-webhook-claim-ledger
Hive-Spec: #14972#webhook-ledger-documentation
Signed-off-by: thatguywob <thatguywob@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Oct 28, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign danathar for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Oct 28, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#14975 📖 docs: explain webhook claim ledger and pending stage recovery same files src/docs/webhooks.md

@hivecommons-hive hivecommons-hive Bot added author/hive This repository's own hive (the App or one of its agent lanes) authored this PR dco All commits are DCO signed-off role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Oct 28, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Conclusion: the content is accurate against v5, but the "pending" framing is now stale — #14971 merged today (2026-10-28 15:27Z), so three passages describe a landed change as unlanded. The earlier decision question on #14975 (land now vs. split out) is moot for the same reason.

What I verified at head de64cb1:

  • src/docs/webhooks.md:71 — heading ### Merge trigger and ledger-to-stage backfill (pending #14971); :73-76 — "proposed in PR #14971, which is not yet merged into v5… at commit 36ed2141d"; :96 — "Until that PR lands, … closing still depends on the scheduled close-on-merge path". All three are false on current v5.
  • The described behaviour does match merged code: prClaimsHookFor and closeOnMergeForDelivery are at src/cmd/hive/webhook_pr_claims.go:23 / :62, the two-minute bound is closeOnMergeDeliveryTimeout at :23 (2 × time.Minute), OnlyPRRepo/OnlyPRNumber are set at :76, reconcileLedgerCoverRecords is called from the eval cycle at src/cmd/hive/main.go:7220 and defined at :10138, and BackfillCoveredByLedger is at src/pkg/github/stage_ledger_backfill.go:42. So the fix is a reword, not a rewrite: drop "(pending #14971)" from the heading, replace :73-76 with a plain "Introduced by #14971", and delete the :96-98 paragraph.

Duplicate note for a maintainer: this PR's head de64cb1 is byte-identical to #14975's head (same SHA, same single-file diff). Both cannot merge. Since #14975 is a fork branch the hive cannot push to and this one is, this PR is the natural survivor for the reword above, and #14975 could be closed in its favour. I have not closed anything.

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Technically accurate, but the new section is already out of date: #14971 merged into v5 at 15:27Z today, and this doc describes it as pending.

I verified the prose against the current v5 tree before reading the PR body:

  • src/pkg/github/webhook_pr_claims.go:96-102 — the seven pull_request actions listed in the doc match the claim-action set exactly; :229-231 the CoveredBy subset (opened/reopened/edited/ready_for_review) matches too.
  • src/pkg/github/webhook_pr_claims.go:175 ApplyPRDelivery, :237 webhookPRCoverTimeout = 2 * time.Minute, :270 coverIssuesForWebhookPR — as documented.
  • src/cmd/hive/webhook_pr_claims.go:23 prClaimsHookFor, :37/:42 the two log messages quoted verbatim, :62 closeOnMergeForDelivery, :76 OnlyPRRepo, OnlyPRNumber, :84 two-minute timeout.
  • src/pkg/github/close_on_merge.go:210 CloseOnMergeLedgerSweep, src/pkg/github/stage_ledger_backfill.go:42 BackfillCoveredByLedger, src/cmd/hive/main.go:10138 reconcileLedgerCoverRecords.

Everything the section says the code does, the code at v5 HEAD (583fe8d) does. So the content is right; the framing is what needs fixing.

Finding (docs-currency, medium) — src/docs/webhooks.md:71-76 and :96-98 (new lines). The heading says (pending #14971), the lead-in says the additions "are proposed in PR #14971, which is not yet merged into v5", and the closing paragraph says "Until that PR lands, … closing still depends on the scheduled close-on-merge path". All three are false as of this afternoon: gh api repos/hivecommons/hive/pulls/14971 → merged: true, merged_at: 2026-10-28T15:27:17Z. Merging this as-is ships an operator doc that tells readers a shipped behaviour does not exist yet.

Ask for the hive fix agent: drop "(pending #14971)" from the heading, replace the "proposed in … not yet merged" lead-in and the "Until that PR lands" paragraph with present-tense description (keep the #14971 reference as provenance if you like), and remove the pin to commit 36ed2141d — the pin only made sense while the target was moving.

Pairing note (intent-alignment, info): this PR's head de64cb1 is byte-identical to #14975 (same SHA). The decision question parked on #14975 — whether to land the section while #14971 was open and conflicted — has been answered by events (#14971 merged). Once the wording above is fixed here, a maintainer could close #14975 in favour of this one; I have not closed anything.

— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

… tense

Hive-Fix-Attempt: 1/6

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: guide <280983584+hivecommons-hive[bot]@users.noreply.github.com>
@hivecommons-hive

Copy link
Copy Markdown
Contributor Author

Superseded by #14975 (earlier fix for #14972). Closing as duplicate.

@hivecommons-hive hivecommons-hive Bot added the hive/superseded Closed by Hive: a different merged PR already landed this change label Oct 28, 2026
@hivecommons-hive hivecommons-hive Bot closed this Oct 28, 2026
thatguywob added a commit to thatguywob/hive that referenced this pull request Oct 28, 2026
Merge current v5 so the documented merge trigger and ledger-to-stage backfill ship with their implementation from hivecommons#14971. Remove the now-stale pending language.

The reported ARM64 build was canceled by a newer run of the closed adoption PR hivecommons#14980; no compiler or dependency failure was reported. Push this updated head to the original PR branch for fresh CI.

Signed-off-by: thatguywob <thatguywob@users.noreply.github.com>
hivecommons-hive Bot pushed a commit that referenced this pull request Oct 28, 2026
…als out of the merge gate (#15011)

* Close superseded hive PRs automatically and re-stage adopted originals out of the merge gate

A hive-authored PR whose closing targets are all closed, one of them by a
different merged PR, and whose head conflicts with the base (or whose files
that PR already covers) is now closed by the hive itself as hive/superseded
with a notice naming the superseding PR: in the self-authored auto-merge
lane before any review is dispatched, in the supersession sweep when the
rebase is refused for a conflict, and in close-on-merge of the superseding
PR. New knob governor.auto_close_superseded (default on); human-authored PRs
are never auto-closed.

A contributor PR adopted in supersede mode leaves stage/085-needs-decision
in the adopting pass when the park was only the review swarm's
requires_human verdict, renders in the CI/Review column with an
'Adopted -> #N' pill, and the duplicate-fix sweep no longer closes the
superseding App PR as a duplicate of the PR it supersedes.

Evidence: #14965 (closed by #14957 for #14952), #14975 -> #14980,
Signed-off-by: Andrew Anderson <andy@clubanderson.com>
#14947 -> #14977.

* Move changelog fragment to repo-root changelog.d

Signed-off-by: Andrew Anderson <andy@clubanderson.com>

---------

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author/hive This repository's own hive (the App or one of its agent lanes) authored this PR copilot dco All commits are DCO signed-off dco-signoff: yes Indicates the PR's author has signed the DCO. hive/superseded Closed by Hive: a different merged PR already landed this change role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) size/M Denotes a PR that changes 30-99 lines, ignoring generated files. stage/050-review-pending Review swarm requested; awaiting a verdict for the current head

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Review backlog (docs-currency): webhooks.md never documents the pull_request→claim-ledger write or the new merge trigger / ledger backfill

1 participant