educates-release-notes

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