Skip to content

🌱 refactor: split API reference into area files - #15303

Closed
thatguywob wants to merge 4 commits into
hivecommons:v5from
thatguywob:refactor/15299-source-layout
Closed

thatguywob wants to merge 4 commits into
hivecommons:v5from
thatguywob:refactor/15299-source-layout

Conversation

@thatguywob

Copy link
Copy Markdown
Contributor

Summary

Route changes currently force unrelated PRs to repair citations in one shared API reference. Split the route tables into 15 area files under src/docs/api-reference/, retaining every existing section heading and anchor in api-reference.md as a link to the corresponding area. Update relative links in the moved content; preserve route descriptions and citations.

The citation checker now walks the index and area directory by default, including when the index is passed explicitly by check-docs-citations.py --fix. It also accepts a directory or a single area file, continues repairing other areas after an unresolved citation, and rewrites only files with resolvable drift. Legacy single-file references remain supported. Update contributor guidance and CI diagnostics to point at the area files.

Related issues

Refs #15299 — implements API-reference part 2; dashboard part 1 remains in #15300. This PR intentionally leaves the issue open until both parts land.

Testing

  • Added citation-checker fixtures covering default/index/directory/area scopes, nested areas, failure aggregation, continued repairs, and unchanged contents/timestamps for unaffected files.
  • Not run locally: AGENTS.md reserves tests and docs/citation guards for CI. Existing Docs Link Check jobs run the extended self-test and validate links, anchors, and citations.
  • No runtime or served dashboard changes. This is a source-layout/tooling refactor; no-changelog applies.

— hive: backend=codex

Closes #15299


🐝 Hive Agent: contributor | SHA: bf6c94b87

Move route tables into focused area documents and keep legacy section anchors in the index. Walk all reference areas for citation checks and repair only drifted files; retain explicit single-file and legacy layout support.

Co-authored-by: clubanderson <407614+clubanderson@users.noreply.github.com>

Hive-Run: hivecommons#15299
Hive-Plan: issue-15299/part-2-api-reference
Hive-Spec: issue-15299#part-2
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 29, 2026
@thatguywob
thatguywob requested a review from hanthor as a code owner October 29, 2026 04:43
@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 kellyaa 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

@thatguywob
thatguywob requested a review from Danathar as a code owner October 29, 2026 04:43
@kubestellar-prow kubestellar-prow Bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Oct 29, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

@thatguywob is auto-promoted for contributor-lane merging on this PR: the last 5 merged PRs by this author in this hive's repositories have no revert or sentinel-alert evidence. CI, reviewer verdict, diff fences, soak, holds and branch protection still apply.

@hivecommons-hive hivecommons-hive Bot added author/clanker A contributor's own hive authored this PR under their login 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/072-returned-to-contributor Contributor PR: CI red, changes requested or conflicting; diagnosis posted, author must act labels Oct 29, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

@thatguywob this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Failing checks:

  • changelog-fragment-guard

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Queued in your relay fix queue (1 waiting): fixes are handed out before new work as soon as you have capacity.

Signed-off-by: thatguywob <thatguywob@users.noreply.github.com>
Signed-off-by: thatguywob <thatguywob@users.noreply.github.com>
@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

This PR conflicts with v5 itself. Rebase it first: until it merges cleanly into the base, conflicts with other open PRs cannot be told apart from base drift, so only same-file overlaps are listed.

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
#15427 ✨ tracker: merge queue position on the chevron, stable wording, stall warning same files src/docs/api-reference/health-status-events.md
#15429 ✨ governor: merge-hotspot advisor files modularize issues for the ci-maintainer same files src/docs/api-reference/health-status-events.md

@hivecommons-hive

Copy link
Copy Markdown
Contributor

@thatguywob this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Review asks:

  • the branch conflicts with the base and needs a rebase

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Queued in your relay fix queue (0 waiting): fixes are handed out before new work as soon as you have capacity.

Signed-off-by: thatguywob <thatguywob@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Oct 29, 2026
@github-actions github-actions Bot added the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Oct 29, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

@thatguywob this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Review asks:

  • the branch conflicts with the base and needs a rebase

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Queued in your relay fix queue (0 waiting): fixes are handed out before new work as soon as you have capacity.

@hivecommons-hive hivecommons-hive Bot added stage/050-review-pending Review swarm requested; awaiting a verdict for the current head and removed stage/072-returned-to-contributor Contributor PR: CI red, changes requested or conflicting; diagnosis posted, author must act labels Oct 29, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

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.

Decision needed: @clubanderson should decide whether #15303 or #15304 lands as part 2 of #15299 — they make the same split with conflicting area-file names, so only one can merge.

This appears to duplicate #15304, which makes the same change: src/docs/api-reference.md becomes an index, the same 15 ## sections move verbatim into src/docs/api-reference/<area>.md, check-api-reference-citations.sh walks the directory and --fix rewrites only the drifted page, and the same workflow/AGENTS.md/test files are updated. Both bodies claim "part 2 of #15299" with #15300 as part 1. I read both diffs in full.

They conflict rather than coexist — 6 of the 15 page names differ, so both cannot merge (conflicts-with-open-pr is already set):

#15303 #15304
agents-controls.md agents-and-controls.md
auth-external-accounts.md auth.md
dashboard-miscellaneous.md dashboard-misc.md
nous-strategy-lab.md nous.md
packs-acmm.md packs-and-acmm.md
snapshots-style.md snapshots-and-style.md

Concrete differences I verified:

  • #15304 also re-points the two in-tree deep links (src/docs/acmm-advisor.md:73, src/docs/agent-configuration.md:130) at the new pages and updates src/README.md / src/docs/documentation-map.md; this PR relies on the retained index anchors only.
  • #15304's check-docs-citations.py passes the api-reference/ directory explicitly (run_api_reference_fix), where this PR expands the index path implicitly inside the shell script (check-api-reference-citations.sh:72-77).
  • This PR's checker is stronger in two small ways: it runs each page in a subshell so an unresolved area still yields a non-zero exit after the others are repaired (:217-224), it walks nested directories, and it fails on an empty directory (:81-84) — #15304's add_doc_path silently passes a directory with no *.md. Worth carrying over if #15304 survives.
  • Body nit: this PR says both Refs #15299 … intentionally leaves the issue open and Closes #15299; GitHub will honour the Closes.

If #15304 (owner-authored, broader link cleanup) is preferred, this one could be closed in its favour. I have not closed anything.

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

@hivecommons-hive hivecommons-hive Bot removed the stage/050-review-pending Review swarm requested; awaiting a verdict for the current head label Oct 29, 2026
@hivecommons-hive hivecommons-hive Bot added the stage/072-returned-to-contributor Contributor PR: CI red, changes requested or conflicting; diagnosis posted, author must act label Oct 29, 2026
@github-actions github-actions Bot removed the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Oct 29, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor
9f03fde

⚠️ Sentinel alert — maintainer review required

Hive flagged this PR (author @thatguywob, head 9f03fded4412) because it matches behaviors that can override security controls, escalate privileges or damage the codebase. This is a heuristic, not an accusation — a maintainer should confirm the change is intended before it merges.

  • sensitive_path — changes 2 sensitive path(s) (Touches a sensitive path (OWNERS, workflows, policies, hive config, security docs, …))
    • .github/workflows/changelog-fragment-guard.yml
    • .github/workflows/docs-link-check.yml

Hive added the sentinel-alert label. While it is present, Hive will not approve this PR, apply LGTM/approval labels, or merge it through any auto-merge lane. Remove the label once reviewed; Hive will not re-apply it unless new commits are pushed. Tune paths and behaviors under sentinel in hive.yaml or the dashboard Security tab.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

⚠️ Hold-gate mergeability: this PR has a real conflict with its base

This PR is hold-gated and has fallen behind its base branch. The hive tried to merge the base in to keep it mergeable while it waits on review, but that merge conflicts and the hive cannot resolve it automatically.

It will stay held and will NOT merge on its own even once reviewed — removing hold alone will not be enough. Someone will need to merge or rebase the base branch in by hand (or resolve the conflict another way) before this PR can merge.

@hivecommons-hive hivecommons-hive Bot added stage/085-needs-decision A human decision is owed: sentinel alert, hold/needs-decision label, human-only rule or parked issue and removed stage/072-returned-to-contributor Contributor PR: CI red, changes requested or conflicting; diagnosis posted, author must act labels Oct 29, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

Needs a decision, not a merge:

Head: verdict requires_human @9f03fde, 27/45 checks green, 18 pending, DCO yes, sentinel alert, soak 0s of 30m0s.

How to release it:

  • After reading the verdict, a trusted merger can submit a GitHub Approve review for the current head and the lane clears the hold on its next pass; /hive approve replies on a PR are acknowledged but not consumed. An ordinary contributor cannot release their own PR.
  • Resolve the sentinel alert and have a maintainer clear its label.

Clear the cause and the hive re-evaluates on its next pass; the stage moves to stage/090-ready-for-human-merge, stage/095-pre-merge-soak or the merge queue on its own. Approval does not bypass CI, hold labels or other merge gates.

@hivecommons-hive hivecommons-hive Bot added stage/072-returned-to-contributor Contributor PR: CI red, changes requested or conflicting; diagnosis posted, author must act and removed stage/085-needs-decision A human decision is owed: sentinel alert, hold/needs-decision label, human-only rule or parked issue labels Oct 29, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

The hive will not publish head 9f03fded4412 upstream: it edits GitHub workflow / action files, which would run with this repository's context once pushed to a branch here. The hive will not re-home or supersede this head.

Ask: a maintainer pushes the fix to this PR's branch and merges it, or cherry-picks the change onto a maintainer-owned branch. Moving to stage/085-needs-decision so a person sees it.

@kubestellar-prow kubestellar-prow Bot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Oct 29, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

PR needs rebase.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

@clubanderson

Copy link
Copy Markdown
Member

Superseded by #15304 (merged), which split docs/api-reference.md into src/docs/api-reference/.md; the tracking issue #15299 is closed. Thanks for the parallel take — closing to keep one PR per issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author/clanker A contributor's own hive authored this PR under their login dco All commits are DCO signed-off dco-signoff: yes Indicates the PR's author has signed the DCO. needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) sentinel-alert size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. stage/072-returned-to-contributor Contributor PR: CI red, changes requested or conflicting; diagnosis posted, author must act

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Monolithic index.html and api-reference.md make every v5 PR conflict with every other

2 participants