ci(release-docs-check): assert [Unreleased] drained on release PR (#837)

[robotrocketscience]

Closes #837.

Bug

release-docs-check in .github/workflows/staging-gate.yml detects release PRs and asserts the ## [X.Y.Z] header and compare-link footnote exist in CHANGELOG/v{major}.md, but does not assert that [Unreleased] was actually drained into the new dated section. The project policy (top-level CHANGELOG.md) explicitly says CI checks both; only the dated-section half was implemented.

The gap surfaced on PR #835 (release: v3.1.1): the PR reached attn:review while five [Unreleased] entries — including #814's breaking-change Removed block — sat undrained, which would have shipped under a SemVer-patch tag.

Fix

Extend the release-docs-check job with one awk pass over the changelog file:

/^## \[Unreleased\]/ { in_unreleased=1; next }
/^## \[/ && in_unreleased { exit }
in_unreleased && NF > 0 && !/^###/ { print }

• Sets in_unreleased=1 on the ## [Unreleased] header
• Exits at the next ## [ header (typically ## [X.Y.Z])
• Inside the window: prints any line that is non-whitespace AND not a ### ... subsection header

Output non-empty → bullet / paragraph content remains in [Unreleased] → fail with an actionable error message that points at the policy and previews the offending lines (head -20).

Empty ### Added / ### Fixed / ### Removed scaffolding is preserved (common pattern for clarity); only entries-under-headers count as un-drained.

Verification

Smoke-tested the awk logic locally against three cases:

case	input	awk output	verdict
current CHANGELOG/v3.md	non-drained [Unreleased]	first 3 bullets surface	would fail a release PR (correctly)
synthetic drained	## [Unreleased]\n\n### Added\n\n### Fixed\n\n## [9.9.9]...	empty	passes (correctly)
synthetic non-drained	as above + - leftover entry under ### Added	- leftover entry	fails (correctly)

The PR itself does not bump pyproject.toml, so the existing head_ver == base_ver short-circuit at the top of the job means this PR's own release-docs-check run will exit 0 (correctly — this is a CI-config PR, not a release PR).

Out of scope

• SemVer-level guard ("patch bump shipping Removed entries with breaking-change language"). Detecting that mechanically requires text classification; the Unreleased-drain check catches the symptom at the release boundary instead.
• Lifting the awk to a standalone scripts/check-changelog-drained.sh with its own unit tests. Worth doing if this check grows more clauses; currently 4 lines of awk is small enough to keep inline.
• The independent release-drafter / publish.yml draft-promotion gap (separate work).

Tier

rook — single-workflow patch, 21 lines added, no production code touched.

[sourcery-ai]

Sorry @robotrocketscience, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Warning

Rate limit exceeded

@robotrocketscience has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 13 minutes and 2 seconds before requesting another review.

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 @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

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 configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: afbe63d4-86ea-47f0-b5a0-ccfdeb094a88

📥 Commits

Reviewing files that changed from the base of the PR and between d3ea7ef and 75d27b3.

📒 Files selected for processing (1)

• .github/workflows/staging-gate.yml

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ci/issue-837-release-docs-unreleased-drain

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[robotrocketscience]

[claim:review:oppenheimer:2026-05-15T02:58:17Z]

[robotrocketscience]

[claim:review:bagheera:2026-05-15T02:58:28Z]

[robotrocketscience]

[release:review:bagheera:2026-05-15T02:58:32Z]

[robotrocketscience]

Approve — clean CI guard, semantically correct

21-line patch to release-docs-check, single signed commit (75d27b38 G), FF on current main, mergeable=CLEAN, discretion grep on full diff = 0 hits. Gated by the existing head_ver != base_ver short-circuit so non-release PRs (this one included) are unaffected.

Awk smoke-tested locally against four cases — all correct:

input	awk output	verdict
current CHANGELOG/v3.md	bullets from [Unreleased] § Fixed / Added	would correctly fail a release PR today
[Unreleased] with empty ### Added / ### Fixed scaffolding only	empty	passes
[Unreleased] with - leftover entry under ### Added	- leftover entry	fails (correct)
changelog with no [Unreleased] header at all	empty	passes (correct)

Edge cases I worked through and are handled:

• [Unreleased] is the last section in the file (no following ## [): awk's exit clause never fires but printing reaches EOF correctly. No false positive.
• Bullet lines containing ### foo mid-line (e.g., - the ### foo case): line starts with -, not ###, so !/^###/ correctly keeps it as content. No false negative.
• The next after setting in_unreleased=1 correctly prevents the ## [Unreleased] header itself from being printed.

One forward-looking note worth flagging on the next iteration (not a blocker): if anyone ever adds a ## Notes or other top-level non-version ## section inside [Unreleased], awk would treat its body as undrained content. Not realistic in keepachangelog format; calling out so reviewers know it's known.

Adding ready-to-merge. Releasing claim.

[robotrocketscience]

[release:review:oppenheimer:2026-05-15T03:00:23Z]

[github-actions]

merge-train: merged 75d27b3 → main via FF push.