| name | release-notes |
| description | Generate a detailed release notes document at docs/RELEASE_X.Y.Z.md by diffing the previous version tag against HEAD. Use when the user asks to write release notes, document a release, or tag a version. |
| user-invocable | true |
| allowed-tools | Bash(git log *) Bash(git diff *) Bash(git show *) Bash(git status *) Bash(git tag *) Read Write Glob Grep |
Generate a release notes document for the current pkcore version.
Steps
1. Determine the version
Read Cargo.toml for the version field. This is <version>. The output file will
be docs/RELEASE_<version>.md.
If that file already exists, read it first — you may be updating or filling in a stub.
2. Find the previous tag
git tag | sort -V
Pick the tag immediately before <version> (e.g. if version is 0.0.42, look for
v0.0.41). This is <prev-tag>. Find its date with:
git show <prev-tag> --no-patch --format="%ci" | head -1
Also capture the current branch:
git branch --show-current
3. Build the change surface
Run these in order — each output informs how deeply to read the source:
git log <prev-tag>..HEAD --oneline
git diff <prev-tag>..HEAD --stat
From --stat, identify:
- Public API files (
src/**/*.rs, excluding test-only modules) with significant
+ line counts — read these files directly (not just the diff) to extract exact
type definitions, method signatures, and doc examples.
- Changed examples (
examples/*.rs) — read to understand usage patterns.
- Infra files (
.github/, rust-toolchain.toml, Cargo.toml) — diff only.
- Doc files (
docs/*.md, ROADMAP.md) — list titles, no deep read needed.
For each significant public API file, run:
git diff <prev-tag>..HEAD -- <file>
then read the current file with Read to get accurate signatures, variant lists,
and doc-test examples. Do not reconstruct code from diff hunks alone — the full
file gives exact types, doc comments, and invariant documentation.
4. Categorize changes
Sort every change into exactly one of these buckets. Omit a section entirely if empty.
| Section | What belongs here |
|---|
| Breaking Changes | Renamed public types/methods/variants, removed public APIs, changed function signatures, new required Error variants that make exhaustive matches fail |
| New Features | New public structs, enums, traits, methods, impl blocks, examples, or feature flags |
| Improvements | Expanded existing public APIs (new impl on existing type), renamed tests, ergonomic improvements, non-breaking additions |
| Infrastructure | CI workflow changes, toolchain bumps, Cargo.toml dependency changes, build config |
| Documentation | New or updated files in docs/, ROADMAP.md, README.md |
| Minor Fixes | Clippy cleanups, formatting, comment corrections, tiny refactors with no API impact |
| Test Coverage Added | New #[test] functions — list by file |
5. Write with depth
For Breaking Changes: include a table of old → new for every affected public
symbol (types, method signatures, impl targets). Explain why the rename or
removal was made. List all internal files that were updated as a result.
For New Features: include:
- A brief description of the problem being solved
- The new public type/method/enum with its exact Rust signature (copy from source)
- A representative usage example — prefer copying from doc tests in the source
- Any invariants or edge-case semantics (all-in run-out, idempotency, etc.)
- A cross-reference to the EPIC doc (
docs/epics/EPIC-NN_*.md) if one exists
For Infrastructure: include exact version numbers (old → new) and, for CI changes,
a snippet of the relevant YAML if it illustrates a non-obvious technique.
For Files Changed: get exact counts from git diff <prev-tag>..HEAD --stat —
do not estimate. Group as: Source, Examples, CI/toolchain, Manifests.
6. Write the document
Write to docs/RELEASE_<version>.md. Use the template below verbatim for structure;
fill every section with real content.
Output template
# pkcore <version> — Release Notes
**Date:** <today's date>
**Branch:** `<current branch>`
**Previous release:** `<prev-tag>` (<prev-tag-date>)
---
## Summary
<2–4 sentence narrative covering the main arcs of this release. Name the EPICs or
themes. Write for a downstream developer skimming to decide whether to upgrade now.>
---
## Breaking Changes
### <Change title>
<One paragraph explaining what changed and why.>
**Affected public surface:**
| Old | New |
|-----|-----|
| `old::path::Type` | `new::path::Type` |
| ... | ... |
<List all internal files updated as a consequence, if the rename was widespread.>
---
## New Features
### <Feature title> (<EPIC-NN> if applicable)
< >
<Describe key invariants, edge cases, error conditions.>
AnotherNewThing
...
Improvements
<What changed and why it's better. Before/after if helpful.>
Infrastructure
<What changed. Include exact version numbers and a YAML/TOML snippet if non-obvious.>
Documentation
New docs
| File | Description |
|---|
docs/epics/EPIC-NN_Name.md | ... |
Updated docs
| File | What changed |
|---|
ROADMAP.md | ... |
Minor Fixes
file.rs: (clippy::<lint> or freeform)
Test Coverage Added
| File | Tests added |
|---|
src/module/file.rs | test_name_a, test_name_b |
Files Changed
Source ( files, +X / −Y lines):
src/foo.rs, src/bar/baz.rs, ...
Examples ( files):
examples/foo.rs (new), examples/bar.rs
CI / toolchain ( files):
.github/workflows/basic.yaml, rust-toolchain.toml
Manifests ( file):
Cargo.toml (version bump X → Y, rust-version A → B)
## Quality bar
- **Breaking Changes:** every renamed or removed public symbol must appear in the
old → new table. If a rename touched 10+ internal files, list them.
- **New Features:** every new public type and method must appear, with its exact Rust
signature (copy from source, do not paraphrase). Include at least one usage example
per new public API; prefer examples from doc tests already in the source.
- **EPIC cross-references:** if the change was part of an EPIC, link the doc stub
(`docs/epics/EPIC-NN_Name.md`) in the feature section.
- **File counts and line numbers** come from `git diff --stat` output — never estimate.
- **Test names** come from reading the test module in the changed file — list them
individually, not as a count.
- **Omit** sections with no content rather than leaving them with placeholder text.
- The document should read as a developer changelog, not a commit log. Write in
present tense describing what the library *now* does, not what the commits *did*.
