Skip to content

docs: the generated env-var table and its count line live in CLAUDE_RULES.md, so every env-var PR conflicts with every other #16317

Description

@mrveiss

Problem

Every PR that adds or removes an AUTOBOT_* env var rewrites the same line of docs/developer/CLAUDE_RULES.md. So any two of those PRs always conflict, not just sometimes.

Evidence

Options

  • A. Drop the count line. The checker already compares the table against the registry, so a count adds nothing the table doesn't show. This removes the always-conflict; neighbouring-row conflicts remain.
  • B. Move the generated section to its own generated doc, leaving a one-line pointer in CLAUDE_RULES.md. The rules doc stops being a merge hotspot, and agents stop loading 220 rows along with the rules.
  • C. Mark the generated file merge=union in .gitattributes. Not recommended: a union merge can duplicate or misorder rows. The checker would catch that loudly, but it trades a conflict for a red.

Recommendation: A + B.

Acceptance criteria

  • No tracked line changes on every env-var add or remove: the count note is gone, or derived when read.
  • The generated env table lives outside CLAUDE_RULES.md, and CLAUDE_RULES.md links to it.
  • generate_env_docs.py and check_env_var_registry.py target the new file, and pre-commit and code-quality.yml are green.
  • Every reference to the table's old location is updated, including the scripts' messages ("Stage the updated CLAUDE_RULES.md…") and the docs.
  • Evidence: two branches that each add one env var at non-neighbouring sort positions merge in either order without conflict. Show it with git merge-tree.

Out of scope

The two file-size ceiling lists (scripts/python_file_size_known_large.py and repo_tests/python_file_size_ratchet_baseline.py), which #16284 also conflicted on, are a deliberate second copy. repo_tests/python_file_size_ratchet_baseline.py:10-19 explains why: "so no ceiling can be raised by editing one file alone". Their conflicts are neighbouring-line conflicts by design.

Sequencing

This lands after the three dropped PRs are rebased and merged, so they don't have to rebase twice.

Activity

  1. added this to the v0.9.0 milestone on Sep 12, 2026
  2. mrveiss commented on Sep 13, 2026

    @mrveiss
    OwnerAuthor

    Evidence from the 2026-09-13 merge trains: this line forced four PRs out of batches or into extra rebases in one morning (#16236, #16458, #16555, #16483). Each rebase costs a full CI run while the hosted-runner pool is saturated. It has also drifted: on main at 995e135 the footer says 221 while the table holds 222 AUTOBOT_ rows, so it's wrong even after clean merges. Worth prioritising in the next train.

  3. mrveiss commented on Sep 13, 2026

    @mrveiss
    OwnerAuthor

    Correction to my evidence comment above: main's footer has not drifted. Counted only inside the generated block (not across the whole file, which includes an AUTOBOT_ row in a separate cache-TTL table), main at 0abe0d4 has 221 rows and footer 221. The rest stands: four PRs were forced out of batches or into rebases by this one line. The count is still error-prone to hand-maintain; my own miscount, and a PR that came out one too high (#16483: 222 rows, footer 223), are both evidence for generating it instead.

  4. mrveiss commented on Sep 14, 2026

    @mrveiss
    OwnerAuthor

    Closure audit (batch vehicle #16702, merge 28228ac).

    AC Verdict Evidence
    No tracked count-line churn met docs/developer/ENV_VARS.md has no "registered as of" count line (grepped, no match)
    Table moved out of CLAUDE_RULES.md, pointer left met docs/developer/CLAUDE_RULES.md:434-441: "The generated reference table... is in ENV_VARS.md"; file is 441 lines (was 669)
    Scripts retarget new file, hooks green met pipeline-scripts/generate_env_docs.py:33 DOCS_PATH = ... / "ENV_VARS.md"; check_env_var_registry.py:216,328 point at ENV_VARS.md; .pre-commit-config.yaml:244 and .github/workflows/code-quality.yml:517 still wire check_env_var_registry.py
    Old-location references updated met .pre-commit-config.yaml, .coderabbit.yaml, .env.example, docs/developer/04-configuration.md all reference ENV_VARS.md; only remaining CLAUDE_RULES.md mentions are unrelated rows and a regression test asserting the table is not there
    git merge-tree evidence, two non-neighbouring branches merge clean met PR #16318 body documents the demonstration directly: before (base d5a0c6dcb, count line in CLAUDE_RULES.md) = 1 conflict each direction; after (branch 4528e671c, ENV_VARS.md, no count line) = 0 conflicts each direction. The structural precondition (no count line + table in its own file) is independently confirmed above

    5/5 met. Kept closed.

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

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions