Skip to content

refactor: src/docs/operator-reference.md is a merge hotspot — split into 4 sections #15510

Closed

Description

@hivecommons-hive

src/docs/operator-reference.md keeps being touched by pull requests that are open at the same time. In the last 7 days 12 distinct PRs changed it, 58 pairs of them were open concurrently, and 0 merge conflicts or rebase failures were blamed on it. Every concurrent pair is a rebase someone (or the merge train) has to redo, and a 2053-line file makes each of those rebases slower and riskier.

This is a document, so the split is by section: each top-level ## area becomes its own file under a directory named after this one, with a short index page that links them (the way docs/api-reference.md became docs/api-reference/<area>.md). Keep every heading anchor reachable from the index.

Evidence

metric value
window 7 days
distinct PRs 12
concurrent PR pairs 58
conflicts attributed 0
lines 2053
kind doc
score 87.0

PRs in window: #15405, #15442, #15449, #15450, #15455, #15468, #15471, #15485, #15486, #15491, #15497, #15506

Sections

  • Agent CLI session recycling
  • Agent Go toolchain shim
  • App self-merge sweep (auto_merge)
  • Configuration blocks
  • Delivery SLA
  • Fleet breaker
  • GitHub API quota
  • GitHub API quota — who is spending it?
  • Governor cadence and budget
  • Image provenance and tags
  • Merge-hotspot advisor (governor.hotspot_*)
  • Minimum required configuration
  • Notable fields
  • Open-PR dispatch guard and duplicate-fix sweep (scanner)
  • OpenTelemetry: GitHub API spend and cache freshness
  • Runtime diagnostics (debug, GOMEMLIMIT, mem: log line)
  • Scheduled-upgrade progress and history
  • Self-reported issues
  • Shared-CI rerun sweep (shared_ci_rerun)
  • Stage labels (governor.labels.stage)
  • Supersession sweep (supersession_sweep)
  • Suspicious-activity alerts (sentinel)
  • What hive writes to GitHub, and when
  • ``HIVE_GITHUB_TOKEN permissions
  • ``cmd/hive flags and environment

Split proposal

  1. src/docs/operator-reference/README.md — index linking every section
  2. src/docs/operator-reference/agent_cli_session_recycl.md — section “Agent CLI session recycling”
  3. src/docs/operator-reference/agent_go_toolchain_shim.md — section “Agent Go toolchain shim”
  4. src/docs/operator-reference/app_self_merge_sweep_aut.md — section “App self-merge sweep (auto_merge)”
  5. src/docs/operator-reference/configuration_blocks.md — section “Configuration blocks” and the 21 remaining sections

Don't splinter

  • At most 4 resulting files, each at least 150 lines; fewer is better.
  • No behaviour change; the package, its exported API and every import path stay the same.
  • Tests move with the code they cover; no new test helpers.
  • One PR; land it when the file has no open PRs against it.

Filed by the hive's merge-hotspot advisor (GET /api/hotspots). It will not file another issue for this file while this one is open.

Activity

  1. added
    kind/cleanupCategorizes issue or PR as related to cleaning up code, process, or technical debt.
    agent/ci-maintainerCreated or modified by the ci-maintainer agent
    on Oct 29, 2026
  2. added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    on Oct 29, 2026
  3. hivecommons-hive commented on Oct 29, 2026

    @hivecommons-hive
    ContributorAuthor

    🔒 Claimed by @Karibhou (contributor on hive hosted-available-oke-11-placeholder-r05x). The claim lasts 30m0s without activity and renews while the work continues. Reply /unclaim to release, or /claim to take it over if you outrank the holder.

  4. hivecommons-hive commented on Oct 29, 2026

    @hivecommons-hive
    ContributorAuthor

    🔓 Claim by @Karibhou released (lease expired).

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent/ci-maintainerCreated or modified by the ci-maintainer agenthelp wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.kind/cleanupCategorizes issue or PR as related to cleaning up code, process, or technical debt.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions