Repository navigation
π docs: split the operator reference - #15731
Conversation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
Open PR overlap checkBase branch: Conflicts are checked with every PR merged onto the current tip of
|
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>
df6fb57 to
b55d8b1
Compare
|
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: β hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88 |
|
stage 080-awaiting-merge-admission β 050-review-pending: required-check-pending:Sign-off survives the squash |
There was a problem hiding this comment.
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
|
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: β hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88 |
There was a problem hiding this comment.
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.mdis a content page, not the index #15510 asked for. The issue's split proposal makesoperator-reference/README.md"index linking every section"; at head it holds the first 14 sections (src/docs/operator-reference/README.md:5onward, 709 lines) and its only navigation is[Contents](../operator-reference.md)atREADME.md:3. The actual index is the parent stubsrc/docs/operator-reference.md, matching theapi-reference.mdprecedent, so the contract is met β but anyone browsing theoperator-reference/directory on GitHub lands on a partial page with no links toruntime-and-quota.mdorsweeps-and-operations.md. Consider renamingREADME.mdto 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
There was a problem hiding this comment.
Style review (head ff5bb5b) β one in-scope gap, one naming advisory.
-
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-118carries 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. -
operator-reference/README.mdis 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_mergesweep). Its siblings are area-named (runtime-and-quota.md,sweeps-and-operations.md), theapi-reference/precedent cited by #15510 uses<area>.mdwith no README, and the issue's proposal reservesREADME.mdfor the index. Renaming it to an area name (e.g.configuration-and-approval.md) and updating the 11 stub links + the back-link atsweeps-and-operations.md:126would 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>
There was a problem hiding this comment.
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 undersrc/(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 stubsrc/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 intooperator-reference/{README,runtime-and-quota,sweeps-and-operations}.mdland 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.gonow 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>
There was a problem hiding this comment.
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 atv5d9e14fd) againstoperator-reference/{README,runtime-and-quota,sweeps-and-operations}.mdplus 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 bothoperator-reference.md#β¦references from Go/JS resolve against it.python3 src/scripts/check-docs-links.py src/docsis clean at this head (289 files), as isdocs/. - Test change is right.
settings_help_11213_test.go:60-61now 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
There was a problem hiding this comment.
Verified the split mechanically against the diff; this looks correct to me.
- No content lost. Diffing the removed lines of
src/docs/operator-reference.mdagainst 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 stuboperator-reference.mddefines 56 matching<a id>anchors, so the inboundoperator-reference.md#β¦links insrc/README.md,src/docs/dashboard.md,src/docs/acmm-policy-matrix.md,src/crux/proxy/agent_github_budget.goand others still resolve. Therelative links and anchors resolvecheck is green. settings_help_11213_test.go:60-61now 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
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>
There was a problem hiding this comment.
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-sentinellink retargeted tosweeps-and-operations.md#β¦(runtime-and-quota.md:186). All relative.mdlinks 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 inboundoperator-reference.md#β¦links elsewhere undersrc/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
|
Thank you for your contribution! Your PR has been merged. We'd love to hear how your experience was: share feedback |
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
df6fb5775650as pushed by @Karibhou (forkKaribhou/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 theirSigned-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.