Skip to content

πŸ“– docs: split the operator reference - #15731

Merged
hivecommons-hive[bot] merged 29 commits into
v5from
hive/adopt-15516
Oct 31, 2026
Merged

hivecommons-hive[bot] merged 29 commits into
v5from
hive/adopt-15516

Conversation

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Supersedes #15516 (adopted in place, re-homed because a hive commit on the contributor branch cannot carry a squash-safe sign-off; original commits by @Karibhou preserved).

Closes #15510

This branch is #15516's head df6fb5775650 as pushed by @Karibhou (fork Karibhou/hive), unchanged. Last lane reason on the original: conflicting.

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.

Sign-off attribution: the original PR would squash the App's signed fixes as the contributor. This App-authored superseder keeps every original commit and sign-off unchanged and attributes the squash to the App instead. DCO and all merge gates still apply here.

Conflicts with v5: the contributor head could not be replayed onto the base, so this copy opened as it is and the hive's fixer is resolving the conflicts on this branch (rebase-resolve episode, two attempts). If both fail the PR parks for a person: adopt the commits into a fresh branch, or close it as superseded.

@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Oct 30, 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 nicholasjackson 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 needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Oct 30, 2026
@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 stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it labels Oct 30, 2026
@github-actions

github-actions Bot commented Oct 30, 2026 •

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
#15890 πŸ› dashboard: point operator-reference help marks at the section sub-pages same files src/pkg/dashboard/settings_help_11213_test.go

@hivecommons-hive hivecommons-hive Bot added the role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) label Oct 30, 2026
Karibhou and others added 4 commits October 30, 2026 08:29
Hive-Run: #15510
Hive-Plan: operator-reference section split
Hive-Spec: issue-15510#split-proposal
Signed-off-by: Karibhou <157208370+Karibhou@users.noreply.github.com>
Signed-off-by: Karibhou <157208370+Karibhou@users.noreply.github.com>
Signed-off-by: Karibhou <157208370+Karibhou@users.noreply.github.com>
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
@hivecommons-hive

Copy link
Copy Markdown
Contributor Author

hive/awaiting-ci: rebased onto v5 and resolved conflicts in src/docs/operator-reference.md (kept split stub; v5's link/row updates carried into the split pages) and src/docs/operator-reference/README.md; CI pending β€” sweep will merge when green.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

β€” hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

@kubestellar-prow kubestellar-prow Bot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Oct 30, 2026
@github-actions github-actions Bot added copilot conflicts-with-open-pr Open PR has a merge conflict with another open PR labels Oct 30, 2026
@hivecommons-hive hivecommons-hive Bot added stage/050-review-pending Review swarm requested; awaiting a verdict for the current head stage/080-awaiting-merge-admission CI green, verdict approve, no modifiers; the automerge lane has not admitted it yet and removed stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Oct 30, 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.

Reviewed β€” no findings from this perspective.

β€” hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot added stage/080-awaiting-merge-admission CI green, verdict approve, no modifiers; the automerge lane has not admitted it yet stage/050-review-pending Review swarm requested; awaiting a verdict for the current head and removed stage/050-review-pending Review swarm requested; awaiting a verdict for the current head stage/080-awaiting-merge-admission CI green, verdict approve, no modifiers; the automerge lane has not admitted it yet labels Oct 30, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor Author

stage 080-awaiting-merge-admission β†’ 050-review-pending: required-check-pending:Sign-off survives the squash

@hivecommons-hive hivecommons-hive Bot added stage/070-fixing Hive-authored PR: CI red, changes requested or needs rebase; a hive agent is fixing it and removed stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Oct 30, 2026
@github-actions github-actions Bot removed the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Oct 30, 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.

Reviewed (correctness, delta a1c8b10…→b0f3a4a) β€” previous docs-currency finding is fixed: src/docs/operator-reference.md:1 now carries # Hive operator reference.

The delta is the rebase onto v5. Every line of the v5 operator-reference.md at merge-base 6e32e8e is present in the split files (only differences are intentional ../ / cross-file link rewrites, e.g. operator-reference/README.md:195-196, runtime-and-quota.md:182, sweeps-and-operations.md:126), and the three v5 additions (toast_info_s/toast_error_s/merged_hold_s at runtime-and-quota.md:478-480, the onboarding section at runtime-and-quota.md:539, the merge-train / soak_minutes row updates at README.md:436,451) were carried correctly.

Advisory (low, non-blocking): the stub index in src/docs/operator-reference.md lists every other #### heading (e.g. lines 91, 93) but not the newly merged #### Onboarding errors point to the Getting Started guide (runtime-and-quota.md:539). Nothing links to that anchor today and it is reachable via its parent HIVE_GITHUB_TOKEN permissions entry (stub line 101), so this is a one-line follow-up, not a blocker.

β€” hive: agent=adjudicator-3 backend=copilot model=claude-fable-5.1 copilot=1.0.88

Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>

# Conflicts:
#	src/docs/operator-reference.md
@hivecommons-hive

Copy link
Copy Markdown
Contributor Author

hive/awaiting-ci: merged v5 into the branch and re-homed the v5 operator-reference.md edits into the split documents (auto_merge.hive_superseding.auto_merge row -> operator-reference/README.md; Notification mode section -> operator-reference/sweeps-and-operations.md). CI pending β€” sweep will merge when green.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

β€” hive: agent=scanner 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.

Reviewed β€” no findings from this perspective.

β€” hive: agent=adjudicator-2 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.

Reviewed β€” no findings from this perspective.

β€” hive: agent=adjudicator 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.

Reviewed (intent-alignment) β€” the split satisfies #15510: all 55 ##/### headings from the base file are present across the three new pages (content identical modulo ../ link rewrites), every old anchor is kept reachable via <a id> + link in src/docs/operator-reference.md:12-119, and all relative links/anchors in the four files resolve. Three content files, each β‰₯ 150 lines, matches the "at most 4 files" bound.

One advisory, non-blocking:

  • README.md is a content page, not the index #15510 asked for. The issue's split proposal makes operator-reference/README.md "index linking every section"; at head it holds the first 14 sections (src/docs/operator-reference/README.md:5 onward, 709 lines) and its only navigation is [Contents](../operator-reference.md) at README.md:3. The actual index is the parent stub src/docs/operator-reference.md, matching the api-reference.md precedent, so the contract is met β€” but anyone browsing the operator-reference/ directory on GitHub lands on a partial page with no links to runtime-and-quota.md or sweeps-and-operations.md. Consider renaming README.md to a section name (e.g. configuration-and-approval.md) and adding a sibling-page list to the top of each page in a follow-up.

β€” hive: agent=adjudicator 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.

Style review (head ff5bb5b) β€” one in-scope gap, one naming advisory.

  1. Two pre-existing anchors dropped from the index (in-scope, #15510: "Keep every heading anchor reachable from the index"). The stub index at src/docs/operator-reference.md:13-118 carries 53 <a id> shims, but two headings that existed at the merge-base (operator-reference.md:1218, :2127) have no entry: ### Notification mode (\github.notifications.mode`)β†’ nowsrc/docs/operator-reference/sweeps-and-operations.md:506, and #### Onboarding errors point to the Getting Started guideβ†’ nowsrc/docs/operator-reference/runtime-and-quota.md:539. src/docs/agent-configuration.md:1137still linksoperator-reference.md#notification-mode-githubnotificationsmode, which after this PR lands on a page without that anchor. Fix: add the two + link rows to the stub (sub-items under "What hive writes to GitHub, and when" and "GitHub App permissions …" respectively). The loosenedsettings_help_11213_test.go:60-61` only guards dashboard help marks, so it will not catch this.

  2. operator-reference/README.md is a content page, not an index (advisory). It opens with [Contents](../operator-reference.md) (README.md:3) and then holds ~700 lines of sections (toolchain shim β†’ auto_merge sweep). Its siblings are area-named (runtime-and-quota.md, sweeps-and-operations.md), the api-reference/ precedent cited by #15510 uses <area>.md with no README, and the issue's proposal reserves README.md for the index. Renaming it to an area name (e.g. configuration-and-approval.md) and updating the 11 stub links + the back-link at sweeps-and-operations.md:126 would keep the directory self-describing on GitHub's folder view.

β€” hive: agent=adjudicator backend=copilot model=claude-fable-5.1 copilot=1.0.88

Hive-Fix-Attempt: 2/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 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.

Looks correct to me β€” verified the split mechanically against the tree at 13ca062, not just the diff.

  • Inbound anchors preserved. All 19 distinct operator-reference.md#… anchors referenced elsewhere under src/ (e.g. #image-provenance-and-tags Γ—6, #what-hive-writes-to-github-and-when Γ—5, #fleet-breaker, #merge-hotspot-advisor-governorhotspot_) resolve to an explicit <a id> in the new stub src/docs/operator-reference.md.
  • No headings lost. Every ##–###### heading of the old page has a matching anchor in the stub, and all 55 stub links into operator-reference/{README,runtime-and-quota,sweeps-and-operations}.md land on an existing heading.
  • Relative links re-based. The 89 relative file links inside the three new files (now one directory deeper: ../webhooks.md, ../../deploy/...) all point at files present in the tree. The ~80 old lines that don't reappear verbatim are exactly these re-based link lines, not dropped content.
  • settings_help_11213_test.go now also accepts <a id="…"> anchors, which is what the stub relies on; the previous heading-only check would otherwise have failed on the redirect page.

Nothing to change from my side.

β€” hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

Carry the new 'Abandoned contributor PRs' section (#15877) into
operator-reference/README.md and index it from the stub page.

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

@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.

Read this as a move, not as 4,600 lines of prose, and the move checks out:

  • Nothing dropped. A line-set diff of the old src/docs/operator-reference.md (2,259 lines at v5 d9e14fd) against operator-reference/{README,runtime-and-quota,sweeps-and-operations}.md plus the new stub finds every non-blank line present once ../ link rewrites are normalised; the four residual lines are table rows / sentences whose only difference is a relative link rewritten for the new directory (e.g. README.md:218-219, sweeps-and-operations.md:126, runtime-and-quota.md:182).
  • Inbound anchors survive. The stub keeps an <a id="…"> for every old heading, and both operator-reference.md#… references from Go/JS resolve against it. python3 src/scripts/check-docs-links.py src/docs is clean at this head (289 files), as is docs/.
  • Test change is right. settings_help_11213_test.go:60-61 now accepts an explicit <a id> anchor as well as a heading, which is exactly what the stub provides.

Remaining red (Sign-off survives the squash cancelled, tide pending) looks like run cancellation from the repeated v5 merges rather than this diff. Not approving β€” a human signature is still needed β€” but I found nothing that should block it.

β€” 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.

Verified the split mechanically against the diff; this looks correct to me.

  • No content lost. Diffing the removed lines of src/docs/operator-reference.md against the lines added to the three new files leaves only four unmatched lines, all of which are cross-file link rewrites (#suspicious-activity-alerts-sentinel β†’ sweeps-and-operations.md#…, earlier Approve* above β†’ … in [App self-merge sweep](README.md#…)).
  • Every old anchor stays reachable. The old file had 56 real headings (the 57th match is a # or: shell comment inside a code block); the stub operator-reference.md defines 56 matching <a id> anchors, so the inbound operator-reference.md#… links in src/README.md, src/docs/dashboard.md, src/docs/acmm-policy-matrix.md, src/crux/proxy/agent_github_budget.go and others still resolve. The relative links and anchors resolve check is green.
  • settings_help_11213_test.go:60-61 now accepts <a id="…"> as well as a heading, which is what lets the settings help links keep pointing at the stub.

One note on shape for the hive to weigh, not a defect: #15510 says "each top-level ## area becomes its own file … with a short index page". This lands as three files of 732 / 648 / 879 lines (README.md carries 8 sections including Configuration blocks, the most-touched area), with the stub acting as the index. That is the same grouping the api-reference/ split used, so I think it satisfies the issue, but README.md will stay a hotspot.

β€” hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

hivecommons-hive Bot and others added 2 commits October 31, 2026 00:51
Resolve the operator-reference.md conflict by keeping the redirect stub and
porting the #15904 webhook wording (issues opened/labeled/unlabeled wake
evaluation, CEL trigger pointer, Agent Channels kick-only) into
operator-reference/runtime-and-quota.md.

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

@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.

Checked this split mechanically against the v5 tree rather than by eye. Looks correct to me.

What I verified:

  • Content preserved. Every non-blank line of the old src/docs/operator-reference.md (1,991 lines) appears verbatim in one of the three new parts, except the intro paragraph (kept in the stub) and 8 lines whose only change is relative-link depth for the new directory β€” e.g. ../../.github/workflows/docker.yml β†’ ../../../.github/workflows/docker.yml (sweeps-and-operations.md:626), ../deploy/… β†’ ../../deploy/… (:660), and the in-page #suspicious-activity-alerts-sentinel link retargeted to sweeps-and-operations.md#… (runtime-and-quota.md:186). All relative .md links in the three parts resolve to files in the PR tree.
  • Anchors preserved. The stub carries an <a id="…"> for 56 of the 58 old heading slugs; the two absent are the H1 title and a # line inside a code block. All 41 inbound operator-reference.md#… links elsewhere under src/ resolve to a stub id, and every stub link resolves to a heading in its target part.
  • src/pkg/dashboard/settings_help_11213_test.go:60-61 β€” the help-link test now also accepts an <a id="…"> match, which is what keeps the existing Settings help marks valid against the stub without editing them.

Net: a mechanical split with no content change; the stub keeps old deep links working.

β€” hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive

Copy link
Copy Markdown
Contributor Author
Evidence bundle `#157312f8d98c` sha256:801e93ae9378e185c88058b43c6c539f8267fbae830e6be2d5e7a25bbad7804e β€” download from the dashboard or `hivectl review evidence #15731`.

@github-actions

Copy link
Copy Markdown
Contributor

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback

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. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

refactor: src/docs/operator-reference.md is a merge hotspot β€” split into 4 sections

1 participant