| name | educates-release-notes |
| description | Create release notes for an Educates version. Invoke when asked to "create release notes", "prepare for a release", "generate release notes", or "document changes for version X.Y.Z". Creates a versioned markdown file in project-docs/release-notes/ and updates project-docs/index.rst. |
| argument-hint | <version> (e.g. 4.1.0) |
| allowed-tools | Read, Glob, Bash |
Educates Release Notes Creation
Create release notes for version $ARGUMENTS of the educates-training-platform.
If no version is specified in $ARGUMENTS, check project-docs/release-notes/ for the latest version-*.md file and increment the patch version.
Step 1: Determine the Version
Use the version from $ARGUMENTS (e.g. 4.1.0). If not provided:
ls project-docs/release-notes/version-*.md | sort -V | tail -1
Increment the patch version (or minor/major as appropriate).
Step 2: Find the Previous Release
ls project-docs/release-notes/version-*.md | sort -V
Identify the version immediately before the target version. Then find its git tag or the commit where it was merged. Educates release tags are plain X.Y.Z (and X.Y.Z-alpha.N/-beta.N/-rc.N pre-releases) with no v prefix:
git tag --sort=-version:refname | grep -E '^[0-9]' | head
git log --oneline --grep="version-<previous>" -- project-docs/release-notes/
Step 3: Analyze Git Changes
Get all commits since the previous release:
git log --oneline <previous-tag-or-commit>..HEAD
Get changed files:
git diff --name-only <previous-tag-or-commit>..HEAD
git diff --stat <previous-tag-or-commit>..HEAD
Get commit messages formatted for analysis:
git log --pretty=format:"%s" <previous-tag-or-commit>..HEAD
Check for merge commits (feature branches):
git log --merges <previous-tag-or-commit>..HEAD
Step 4: Categorize Changes
Map changes to sections by scanning commits and file diffs:
| Category | What to look for |
|---|
| New Features | New files, new commands, new config options; commit keywords: "add", "new", "feature", "support for" |
| Features Changed | Modified existing files, version bumps, config changes; keywords: "update", "change", "modify", "improve", "refactor" |
| Bugs Fixed | Error handling, corrections; keywords: "fix", "bug", "error", "issue", "correct" |
| Deprecations | Things still supported but on the way out; keywords: "deprecate", "deprecated". Note the removal timeline (and any upstream timeline it tracks). |
| Known Issues | Manual entry โ from issue tracker or known limitations |
A user-facing change is only "done" when it has a release-notes entry โ this is a
project norm (see CLAUDE.md), so the running version-*.md may already carry
many entries. Treat your job as filling gaps and tidying, not writing from scratch.
Common patterns:
go.mod/go.sum changes โ dependency updates (Features Changed)Dockerfile changes โ base image or tool version updates (Features Changed)- New files in
project-docs/ โ documentation (New Features or Features Changed)
- kubectl version blocks in
workshop-images/base-environment/Dockerfile โ Kubernetes version support change
Step 5: Create the Release Notes File
Create project-docs/release-notes/version-{x.y.z}.md using this exact format:
Version {x.y.z}
=============
New Features
------------
* Description of new feature.
Features Changed
----------------
* Description of changed feature.
Bugs Fixed
----------
* Description of bug fix.
Deprecations
------------
* Description of a feature that still works but is slated for removal, with the
removal timeline (if any).
Known Issues
------------
* Description of known issue (if any).
Formatting rules:
- Main heading uses
= underline (same length as the heading text)
- Section headings use
- underline
- Bullet points use
*
- Omit sections that have no entries
- Write in third person, concise, specific
- Include version numbers for dependency updates
- Clearly flag breaking changes
Step 6: Update project-docs/index.rst
Read project-docs/index.rst and find the Release Notes: toctree section (around line 80โ82). Add the new entry at the top of the list (newest first):
.. toctree::
:maxdepth: 2
:caption: Release Notes:
release-notes/version-{x.y.z}
release-notes/version-{previous}
...
Maintain 2-space indentation and keep entries sorted newest first.
Step 7: Review
- Verify version number is correct and consistent in filename and heading
- Confirm all major changes from git log are covered
- Check formatting matches existing release notes files (read one for comparison)
- Verify the
index.rst entry was added correctly and the file renders as valid RST
