Skip to content

Commit 66b7df8

Browse files
GlitterKillGlitterKill
committed
feat: enforce complete release summary coverage
1 parent cf6b4d7 commit 66b7df8

6 files changed

Lines changed: 1521 additions & 26 deletions

File tree

‎.agents/skills/release-notes/SKILL.md‎

Lines changed: 46 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -6,22 +6,23 @@ disable-model-invocation: true
66

77
# Release Notes Generator
88

9-
Generate a CHANGELOG entry for the next release by analyzing git history since the last tag.
9+
Generate a CHANGELOG entry for the next release by analyzing the complete release range and preserving its validated target through publication.
1010

1111
## Steps
1212

13-
1. **Get the last tag and version**:
14-
```bash
15-
git describe --tags --abbrev=0
16-
```
17-
Also read the current version from `package.json`.
13+
1. **Set the release identities**:
14+
- Read `<version>` from `package.json`.
15+
- Set `<tag>` to `v<version>`.
16+
- Set `<baseTag>` to the previous annotated release tag.
17+
- Set the pre-release `<target>` to `HEAD`.
1818

19-
2. **Get all commits since the last tag**:
19+
2. **Read the complete history**:
20+
Use the complete, unbounded `<baseTag>..<target>` range with full commit OIDs. Do not add `-n`, `--max-count`, date limits, paging limits, or manual truncation.
2021
```bash
21-
git log <last-tag>..HEAD --oneline --no-merges
22+
git log <baseTag>..<target> --format="%H%x09%an%x09%s"
2223
```
2324

24-
3. **Categorize each commit** into these sections (matching the existing CHANGELOG.md format):
25+
3. **Categorize every commit** into these sections, matching the existing `CHANGELOG.md` style:
2526
- **Breaking Changes** — API changes, removed features, migration required
2627
- **Features** — new tools, new CLI commands, new capabilities
2728
- **Enhancements** — improvements to existing functionality
@@ -30,28 +31,48 @@ Generate a CHANGELOG entry for the next release by analyzing git history since t
3031
- **Performance** — speed, memory, or token efficiency improvements
3132
- **Internal** — refactoring, test infrastructure, CI changes (only include if significant)
3233

33-
4. **Read the existing CHANGELOG.md** to match its formatting style (heading levels, bullet format, date format).
34-
35-
5. **Draft the entry** in this format:
34+
4. **Draft concise, grouped summaries**:
35+
Read the existing `CHANGELOG.md` and group related commits into one visible bullet. Put the full OIDs covered by that bullet in the immediately following hidden marker:
3636
```markdown
37-
## [X.Y.Z] - YYYY-MM-DD
37+
- **component**: Concise description of the related change.
38+
<!-- release-note-commits: <full-oid> <full-oid> -->
39+
```
40+
Use only full 40-character OIDs. Keep exactly one visible commit appendix in the generated release notes, and do not repeat per-commit bullets elsewhere.
41+
42+
5. **Present the CHANGELOG draft for review**:
43+
Omit empty sections and match the existing heading, bullet, and date style. Do not write `CHANGELOG.md` until the user approves.
3844

39-
### Features
40-
- **tool-name**: Description of what was added
45+
6. **Validate before the expensive release checks**:
46+
After the approved entry is in the working-tree `CHANGELOG.md`, run:
47+
```bash
48+
npm run prepare-release -- --base-tag <baseTag>
49+
```
50+
Save the full `preReleaseTargetOid` from the machine-readable validation output. Stop on any coverage or target drift failure.
4151

42-
### Bug Fixes
43-
- **component**: What was fixed and why
52+
7. **Create the release commit and annotated tag**:
53+
Commit only the approved release changes, then create the annotated tag:
54+
```bash
55+
git tag -a <tag> -m "Release <tag>"
56+
```
4457

45-
### Security
46-
- **component**: What vulnerability was addressed
58+
8. **Build release notes from the tagged target**:
59+
Immediately after annotated tag creation, run build mode with the exact validated identities:
60+
```bash
61+
node scripts/build-release-notes.mjs build --version <version> --base-tag <baseTag> --target <tag> --pre-release-target <preReleaseTargetOid> --output <output>
4762
```
63+
Do not publish if this command reports coverage or target drift.
4864

49-
6. **Present the draft** to the user for review. Do NOT write it to CHANGELOG.md until the user approves.
65+
9. **Publish the generated file**:
66+
Push the annotated tag only after build mode passes, then publish the exact generated notes file:
67+
```bash
68+
gh release create <tag> --verify-tag --notes-file <output>
69+
```
5070

5171
## Rules
5272

53-
- Omit empty sections (don't include "### Internal" if there are no internal changes)
54-
- Use `**component**:` prefix on each bullet matching the area of code changed
55-
- Keep descriptions concise (one line each)
56-
- Group related commits into single bullets when they address the same change
57-
- Include the commit count summary at the end: `_N commits from M contributors_`
73+
- Analyze the complete, unbounded release range.
74+
- Omit empty sections.
75+
- Use `**component**:` prefixes matching the changed area.
76+
- Keep summaries concise and grouped; never expose coverage markers as visible prose.
77+
- Preserve full-OID coverage from validation through the tagged build.
78+
- Stop at every validation failure; never regenerate against a drifting target.

‎.codex/skills/release-notes/SKILL.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
name: release-notes
3+
description: Generate a CHANGELOG.md entry from git history since the last tag, categorized by type (features, fixes, security, breaking changes). Matches the existing CHANGELOG format.
4+
disable-model-invocation: true
5+
---
6+
7+
# Release Notes Generator
8+
9+
Generate a CHANGELOG entry for the next release by analyzing the complete release range and preserving its validated target through publication.
10+
11+
## Steps
12+
13+
1. **Set the release identities**:
14+
- Read `<version>` from `package.json`.
15+
- Set `<tag>` to `v<version>`.
16+
- Set `<baseTag>` to the previous annotated release tag.
17+
- Set the pre-release `<target>` to `HEAD`.
18+
19+
2. **Read the complete history**:
20+
Use the complete, unbounded `<baseTag>..<target>` range with full commit OIDs. Do not add `-n`, `--max-count`, date limits, paging limits, or manual truncation.
21+
```bash
22+
git log <baseTag>..<target> --format="%H%x09%an%x09%s"
23+
```
24+
25+
3. **Categorize every commit** into these sections, matching the existing `CHANGELOG.md` style:
26+
- **Breaking Changes** — API changes, removed features, migration required
27+
- **Features** — new tools, new CLI commands, new capabilities
28+
- **Enhancements** — improvements to existing functionality
29+
- **Bug Fixes** — corrections to incorrect behavior
30+
- **Security** — vulnerability fixes, hardening
31+
- **Performance** — speed, memory, or token efficiency improvements
32+
- **Internal** — refactoring, test infrastructure, CI changes (only include if significant)
33+
34+
4. **Draft concise, grouped summaries**:
35+
Read the existing `CHANGELOG.md` and group related commits into one visible bullet. Put the full OIDs covered by that bullet in the immediately following hidden marker:
36+
```markdown
37+
- **component**: Concise description of the related change.
38+
<!-- release-note-commits: <full-oid> <full-oid> -->
39+
```
40+
Use only full 40-character OIDs. Keep exactly one visible commit appendix in the generated release notes, and do not repeat per-commit bullets elsewhere.
41+
42+
5. **Present the CHANGELOG draft for review**:
43+
Omit empty sections and match the existing heading, bullet, and date style. Do not write `CHANGELOG.md` until the user approves.
44+
45+
6. **Validate before the expensive release checks**:
46+
After the approved entry is in the working-tree `CHANGELOG.md`, run:
47+
```bash
48+
npm run prepare-release -- --base-tag <baseTag>
49+
```
50+
Save the full `preReleaseTargetOid` from the machine-readable validation output. Stop on any coverage or target drift failure.
51+
52+
7. **Create the release commit and annotated tag**:
53+
Commit only the approved release changes, then create the annotated tag:
54+
```bash
55+
git tag -a <tag> -m "Release <tag>"
56+
```
57+
58+
8. **Build release notes from the tagged target**:
59+
Immediately after annotated tag creation, run build mode with the exact validated identities:
60+
```bash
61+
node scripts/build-release-notes.mjs build --version <version> --base-tag <baseTag> --target <tag> --pre-release-target <preReleaseTargetOid> --output <output>
62+
```
63+
Do not publish if this command reports coverage or target drift.
64+
65+
9. **Publish the generated file**:
66+
Push the annotated tag only after build mode passes, then publish the exact generated notes file:
67+
```bash
68+
gh release create <tag> --verify-tag --notes-file <output>
69+
```
70+
71+
## Rules
72+
73+
- Analyze the complete, unbounded release range.
74+
- Omit empty sections.
75+
- Use `**component**:` prefixes matching the changed area.
76+
- Keep summaries concise and grouped; never expose coverage markers as visible prose.
77+
- Preserve full-OID coverage from validation through the tagged build.
78+
- Stop at every validation failure; never regenerate against a drifting target.

‎docs/release-test.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ This document provides step-by-step testing for SDL-MCP releases. Start with the
2323
Run this first:
2424

2525
```powershell
26-
npm run prepare-release
26+
npm run prepare-release -- --base-tag <previous-tag>
2727
```
2828

2929
`prepare-release` hard-fails on:
@@ -32,6 +32,8 @@ npm run prepare-release
3232
- invalid self tarball dependency in `package.json` (for example `dependencies.sdl-mcp: "file:*.tgz"`)
3333
- published-version collision
3434
- missing changelog entry
35+
- missing or invalid explicit base tag
36+
- incomplete release-note coverage or target drift
3537
- build, lint, typecheck, or test failures
3638
- `npm audit` findings at `high` or above
3739
- missing package contents in `npm pack --json`

0 commit comments

Comments
 (0)