Skip to content

refactor: src/docs/labels-and-control-signals.md is a merge hotspot — split into 4 sections #15675

Closed

Description

@hivecommons-hive

src/docs/labels-and-control-signals.md keeps being touched by pull requests that are open at the same time. In the last 7 days 6 distinct PRs changed it, 6 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 2595-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 6
concurrent PR pairs 6
conflicts attributed 0
lines 2595
kind doc
score 9.0

PRs in window: #15308, #15449, #15491, #15591, #15662, #15668

Sections

  • Blockers (hive:blocker marker)
  • Categories
  • Config that changes label behavior
  • Decision glossary
  • Documented inconsistencies and follow-ups
  • First use: choose the control
  • How labels reach agents
  • Label axes
  • Lifecycle examples
  • Matching rules
  • Non-label equivalents
  • Question auto-close
  • Reference table
  • Repo-card legend vocabulary
  • Stage labels (stage/NNN-*): the pipeline state machine

Split proposal

  1. src/docs/labels-and-control-signals/README.md — index linking every section
  2. src/docs/labels-and-control-signals/blockers_hive_blocker_ma.md — section “Blockers (hive:blocker marker)”
  3. src/docs/labels-and-control-signals/categories.md — section “Categories”
  4. src/docs/labels-and-control-signals/config_that_changes_labe.md — section “Config that changes label behavior”
  5. src/docs/labels-and-control-signals/decision_glossary.md — section “Decision glossary” and the 11 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 30, 2026
  2. added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    on Oct 30, 2026
  3. hivecommons-hive commented on Oct 30, 2026

    @hivecommons-hive
    ContributorAuthor

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

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