github/codegraph
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(claude): rewrite release section for auto-promote workflow + link-ref on promote (#437)

Browse Source 
Two paired updates:

1. **`CLAUDE.md` § Releases** — rewritten to match the actual workflow now
   that #436's auto-promote step lands the entries automatically.

   The old text told Claude to 'Add a new `## [X.Y.Z] - YYYY-MM-DD`
   block at the top of CHANGELOG.md' as the first step. That instruction
   is the exact pattern that caused the v0.9.5 sparse-release-notes
   incident — a hand-added sparse `[X.Y.Z]` block (one early fix
   pre-staged) is what the extractor picked, ignoring everything under
   `[Unreleased]` above it.

   New default: write entries under `## [Unreleased]` during normal
   work. The Release workflow promotes them at release time. The
   formatting rules (sub-section grouping, user-perspective wording,
   issue/PR refs) are preserved. The link-reference rule moves to 'don't
   add it yourself' since `prepare-release.mjs` now appends it.

2. **`scripts/prepare-release.mjs`** — extended to also append a
   `[X.Y.Z]: https://github.com/colbymchenry/codegraph/releases/tag/vX.Y.Z`
   link reference at the end of CHANGELOG.md when promoting (idempotent
   — no-op if one already exists, regardless of where in the file it
   sits). This is what makes the `## [X.Y.Z]` heading text auto-link
   to its release tag in GitHub's renderer; without it the heading still
   renders, just unlinked. 3 new tests cover Case A append, Case B
   append-when-merging, and no-double-add.

940/942 existing tests still pass (2 pre-existing skips); +3 new tests.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Colby Mchenry
2026-05-26 03:25:06 -05:00
committed by GitHub
co-authored by Claude Opus 4.7
parent b77af782c5
commit f6fabe9b5a
3 changed files with 85 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
__tests__/prepare-release.test.ts
+34
View File
@@ -165,6 +165,40 @@ describe('prepare-release.mjs', () => {
});
});
describe('link reference', () => {
it('appends a `[version]: https://...` link reference at EOF when promoting (Case A)', () => {
dir = setup(HEADER + `## [Unreleased]\n\n### Added\n- x\n\n## [1.2.2] - 2026-01-01\n`);
run(dir);
const result = fs.readFileSync(path.join(dir, 'CHANGELOG.md'), 'utf8');
expect(result).toContain(
'[1.2.3]: https://github.com/colbymchenry/codegraph/releases/tag/v1.2.3',
);
});
it('appends a link reference when merging into an existing [version] (Case B)', () => {
dir = setup(
HEADER + `## [Unreleased]\n\n### Added\n- new\n\n## [1.2.3] - 2026-02-02\n\n### Fixed\n- prior\n`,
);
run(dir);
const result = fs.readFileSync(path.join(dir, 'CHANGELOG.md'), 'utf8');
expect(result).toContain(
'[1.2.3]: https://github.com/colbymchenry/codegraph/releases/tag/v1.2.3',
);
});
it('does not double-add an existing link reference', () => {
const ref = '[1.2.3]: https://github.com/colbymchenry/codegraph/releases/tag/v1.2.3';
dir = setup(
HEADER +
`## [Unreleased]\n\n### Added\n- x\n\n## [1.2.2] - 2026-01-01\n\n${ref}\n`,
);
run(dir);
const result = fs.readFileSync(path.join(dir, 'CHANGELOG.md'), 'utf8');
const occurrences = result.split(ref).length - 1;
expect(occurrences).toBe(1);
});
});
describe('extractor integration', () => {
it('the resulting [version] block is what extract-release-notes.mjs would surface', () => {
// Run prepare, then extract — confirm the output contains all the