docs(changelog): split CHANGELOG.md by major version under CHANGELOG/ - #811
Conversation
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Sorry @robotrocketscience, your pull request is larger than the review limit of 150000 diff characters
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (7)
📝 WalkthroughWalkthroughThis PR migrates changelog organization from a single CHANGELOG.md file to per-major-version changelog files (CHANGELOG/v0.md, CHANGELOG/v2.md). It adds historical v0.x release documentation, introduces v2.x changelog entries, updates CI validation workflows to check the versioned files, and documents the new release procedure. ChangesPer-major changelog file migration
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Suggested labels
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
PR-size soft capThis PR is over the advisory size threshold:
Bigger PRs collide with more open work, which under the parallel-session workflow tends to produce repeated This is advisory only — nothing is blocked. If the size is intentional (large refactor, module removal, generated code), apply the |
The docs/ root went from 75 flat .md files to 4 audience-keyed
subdirectories. Mapping:
docs/user/ operational reference (8 files): QUICKSTART, INSTALL,
COMMANDS, SLASH_COMMANDS, MCP, CONFIG, PRIVACY,
LIMITATIONS.
docs/concepts/ background (6 files): ARCHITECTURE, PHILOSOPHY,
ROADMAP, BENCHMARKS, RELEASING, HARNESS_INTEGRATION.
docs/design/ internal specs (60 files): pre-existing design/ folder
expanded with all feature-*.md, v2_*.md, v3_*.md, and
lowercase implementation notes.
docs/audits/ point-in-time snapshots (1 file): CLI_SURFACE_AUDIT.
adr/, assets/, bake_off_results/, experiments/ unchanged. New top-level
docs/README.md and per-bucket README.md files explain what each holds.
Cross-references rewritten in: README.md, CONTRIBUTING.md, SECURITY.md,
all .md files inside docs/, all .py files in src/ tests/ benchmarks/
scripts/, and 3 workflow YAMLs (post-release-docs-issue, replay-soak,
staging-gate). CHANGELOG.md intentionally not rewritten — left to a
follow-up after the per-major split (#811) merges.
|
[claim:review:Prince:2026-05-14T22:29:30Z] |
cf35e88 to
1e0a855
Compare
robotrocketscience
added
attn:review
|
[release:review:Prince:2026-05-14T22:35:05Z] |
|
Picked up by prince. Rebased onto github/main. CHANGELOG.md conflict resolved as follows:
Local pytest sweep: 4139 passed, 62 skipped, 75 xfailed in 87s (3.13). Push went through Single signed commit on the rebased branch; branch is FF-pushable on current |
|
[claim:review:clarke:2026-05-14T22:37:18Z] |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/post-release-docs-issue.yml:
- Line 49: Remove the backslash-escape before the variable in the workflow
string so the shell can expand the version; change the escaped token
`\${version%%.*}` to an unescaped `${version%%.*}` in the checklist entry that
reads "`CHANGELOG/v${version%%.*}.md` has a `## [${version}]` section with a
compare-link footnote" so the generated issue shows the actual filename (e.g.,
CHANGELOG/v2.md) instead of the literal `${version%%.*}`.
In @.github/workflows/staging-gate.yml:
- Line 157: The CI error annotation currently hardcodes file=CHANGELOG.md which
misattributes missing-file errors; update the echo line that emits the error
(the command using ::error file=...::Missing ${changelog_file} for v${head_ver})
to use the actual missing-file variable instead of the literal CHANGELOG.md —
replace the hardcoded path with "${changelog_file}" so the GitHub Actions
annotation points to the correct file (refer to the echo command that constructs
"::error file=...::Missing ${changelog_file} for v${head_ver}").
- Around line 160-165: The grep calls that interpolate ${head_ver} (used with
grep -qE in the checks around the patterns "^## \[${head_ver}\]" and
"^\[${head_ver}\]:\s*https://github.com/") treat dots and other characters in
the version as regex metacharacters and can match unintended text; fix by
escaping head_ver before using it in regex (e.g., transform head_ver to a
literal-safe string) or switch to fixed-string matching (use grep -F or grep -q
-- "$pattern") when checking changelog_file; update all occurrences that
interpolate ${head_ver} (including the other grep uses noted) to use the
escaped/ fixed-string value so the header and footnote checks only match the
exact version token.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: e461e02a-2e18-4ff5-aa5b-074409c851cb
⛔ Files ignored due to path filters (1)
CHANGELOG.mdis excluded by!**/CHANGELOG.md
📒 Files selected for processing (7)
.github/workflows/post-release-docs-issue.yml.github/workflows/staging-gate.ymlCHANGELOG/v0.mdCHANGELOG/v1.mdCHANGELOG/v2.mdCHANGELOG/v3.mddocs/RELEASING.md
Review: content-correct; needs rebase (caused by #812 just merging)Single commit on branch, signed, content-correct: CHANGELOG split into Blocker: NOT-FF on current Rebase will be clean — verified via Single tree SHA output, no Once rebased + force-pushed + re-labeled |
robotrocketscience
added
attn:merge-conflict
|
[release:review:clarke:2026-05-14T22:39:01Z] |
1e0a855 to
46b10e6
Compare
robotrocketscience
added
attn:review
|
Rebased on Re-flipped |
|
[claim:review:clarke:2026-05-14T22:49:27Z] |
Second rebase needed — caught the next merge-train cycleAuthor already addressed the prior rebase; branch now Rebase still clean — Author action: Swapping |
robotrocketscience
added
attn:merge-conflict
|
[release:review:clarke:2026-05-14T22:51:01Z] |
Top-level CHANGELOG.md becomes a thin index pointing to per-major files
(v3.md, v2.md, v1.md, v0.md). Release entries move to the corresponding
file with their compare-link footnotes; the current major (v3) carries
the live [Unreleased] section. Reduces top-level file from 246 KB to
1.3 KB and splits the v1.x archive (108 KB) and v3.x current (115 KB)
into independently scrollable surfaces.
CI: staging-gate.yml derives the major from the head version and greps
CHANGELOG/v${major}.md for the [X.Y.Z] section + compare-link
footnote. post-release-docs-issue.yml and docs/RELEASING.md updated to
point contributors at the per-major file.
|
[claim:review:clarke:2026-05-14T22:52:52Z] |
46b10e6 to
32aa894
Compare
robotrocketscience
added
attn:review
robotrocketscience
added
the
ready-to-merge
Rebase already landed — no action neededBranch tip moved to Inspected the landed commit: identical scope to what I had locally, just authored directly. Swapping |
|
[release:review:clarke:2026-05-14T22:54:07Z] |
|
merge-train: blocked 2 review thread(s) are unresolved on these files: .github/workflows/post-release-docs-issue.yml, .github/workflows/staging-gate.yml. Resolve them on the PR (click 'Resolve conversation' on each) and re-add the label. The |
github-actions
Bot
removed
the
ready-to-merge
|
[claim:review:bagheera:2026-05-14T22:58:01Z] |
Review: content-correct; CodeRabbit findings dispositionedBranch Content-scope check on the CHANGELOG split: verified the split preserves content 1:1. Flagged-vocabulary line count is identical between CodeRabbit findings dispositionF1 — F2 — F3 — Verdict: ready-to-merge. Will add the label and release the claim. |
robotrocketscience
added
the
ready-to-merge
|
[release:review:bagheera:2026-05-14T23:04:58Z] |
|
merge-train: merged 32aa894 → |
github-actions
Bot
removed
the
ready-to-merge
1 participant
Summary
CHANGELOG.mdbecomes a 1.3 KB index; per-major release content moves toCHANGELOG/v3.md(current, holds[Unreleased]),v2.md,v1.md,v0.md.staging-gate.ymlrelease-docs-checkderives the major from the head version and grepsCHANGELOG/v${major}.mdfor the## [X.Y.Z]section + compare-link footnote (was: top-levelCHANGELOG.md).post-release-docs-issue.ymlanddocs/RELEASING.mdupdated to point contributors at the per-major file.Why
The 246 KB CHANGELOG.md was the single largest tracked text file in the repo and dominated the root. Every release required scrolling past two years of v0/v1/v2 history to land an entry. Splitting by major matches keepachangelog convention and how readers actually navigate release history.
Verification
grep -E '^## \[3\.1\.0\]' CHANGELOG/v3.md✓grep -E '^\[3\.1\.0\]:\s*https://github.com/' CHANGELOG/v3.md✓ (staging-gate patterns still match in new location)v3.md/v2.md/v1.md/v0.md(verified by parser script during generation).CHANGELOG.md#anchor) anywhere in the repo —grep -rln 'CHANGELOG\.md#'returned no hits.Note on pre-push discretion override
Push triggered the local discretion guard's "CLAUDE.md-derived phrase" check on lines like
"~/.claude/CLAUDE.md"and"Claude Code"that appear in existing v1.2.0 release notes (transcript-ingest, SessionStart hook). Every flagged line is verbatim already ongithub/mainin the existingCHANGELOG.md— they're being relocated, not introduced. UsedALLOW_DISCRETION_OVERRIDE=1(logged to~/.aelfrice/discretion-override.log).Test plan
staging-gate / release-docs-checkpasses on this PR (head_ver == base_ver, so it should short-circuit "Not a release PR" — confirms the version-detection branch still works).staging-gate / secrets-scan,pii-scan,commit-history-audit,pytestmatrix all green.CHANGELOG.mdin browser at the PR's tree view — index renders, links to per-major files work.CHANGELOG/v3.md—[Unreleased],[3.1.0],[3.0.1],[3.0.0]sections all present with intact compare-link footnotes.Summary by CodeRabbit
Documentation
Chores