release-notes

name

release-notes

description

Write a paste-ready GitHub release-notes draft for Kubriko, summarizing the library changes since the last version bump, grouped by module. Invoke this skill WHENEVER the task involves Kubriko release notes — preparing or cutting a new release, bumping `library.version`, or any request to draft, write, summarize, or update release notes / a changelog / "what changed since the last version". This is the ONLY correct way to produce these notes; do not summarize changes by hand instead. Not triggered by ordinary code edits — only by release/notes work.

Kubriko release notes

Produce a temporary markdown file the user can copy-paste straight into a GitHub release. Match the style of the existing notes at https://github.com/pandulapeter/kubriko/releases.

The notes are for library consumers only. Never mention Showcase, examples, or the app/ shell — changes confined to examples/ or app/ do not belong in the notes at all.

Process

1. Determine the version. The next release version is always library.version in gradle.properties. That file can contain non-UTF8 bytes (the copyright line), which makes grep treat it as binary and print nothing — read it with the Read tool (or grep -a) instead of plain grep.

2. Find the last version bump. Version bumps are commits titled Update library version to "vX.Y.Z":

   git log -1 --grep='Update library version' --format='%H %s'
   

3. List the library changes since that commit — restrict to the published areas right away:

   git log <bump-hash>..HEAD --format='%H %s' -- engine plugins tools
   

4. Read the actual diffs — do not summarize from commit messages. Commit subjects are lossy and often describe the symptom rather than the change. For each commit, inspect what really changed:

   git show <hash> -- engine plugins tools          # full diff
   git show --name-only --format='' <hash> | grep -E '\.(kt|kts)$' | cut -d/ -f1-2 | sort -u   # modules
   

5. Always surface public API changes, additions, and removals. This is the most important part of the notes. Public API lives outside implementation/ packages, so check those files specifically:

   git diff <bump>..HEAD --name-status -- engine plugins tools | grep -v '/implementation/' \
     | grep -viE 'test|Impl\.kt'
   

   For every hit, read the diff and call out, explicitly:

   • New types, traits, trait properties, manager functions, newInstance parameters, enum/sealed cases.
   • Changed signatures, defaults, or renamed members.
   • Removed/replaced members (added/deleted files show as A/D) — these are breaking; say so plainly.
   • Observable behavior changes of existing public API (e.g. forces becoming frame-rate independent, particles no longer appearing in ActorManager.allActors), even when the signature is unchanged.

6. Filter to consumer-facing substance. Drop pure internal maintenance with no observable effect (deprecation-warning cleanups, internal refactors) and anything touching only examples//app/. When a commit's subject mentions a platform (e.g. "Android 14 crash") but the fix lives in a library module, keep it and attribute it to that module.

7. Write the draft to .release-notes/<version>.md (create the dir; /.release-notes/ is gitignored so these scratch files stay untracked). The file's contents are the release body and nothing else — no preamble, no "generated by", no meta commentary. Tell the user the path and that it's a throwaway to delete after pasting.

Style

Mirror the existing releases:

• Group by module / subsystem, as bold colon-terminated headings, then * bullets. Use the real module names: **Engine:**, **Physics plugin:**, **Particles plugin:**, **Keyboard and pointer input plugins:**, **Tools:**, **Dependencies:**. Order roughly by significance, engine first. Do not group by change type (no "Bug fixes" / "Performance" sections).
• Lead each module's bullets with API changes, then behavior changes, then performance, then fixes.
• Every bullet is a specific, technical, complete sentence, ending with a period. Name the actual thing changed and, when it isn't self-evident, the why or the impact ("...to save power during idle states", "...for a large reduction in per-frame overhead").
• Backtick every code identifier — managers, traits, APIs, types, parameters (ViewportManager, TargetFrameRate, Visible.isAlwaysVisible).
• Link newly introduced public classes/types. When the notes mention a public class, interface, or type that is new this release (a freshly added file outside implementation/, e.g. TargetFrameRate), make its first mention a link to its source file at the release tag: [TargetFrameRate](https://github.com/pandulapeter/kubriko/blob/<version>/<path/to/File.kt>) — keep the identifier backticked inside the link text. Use the library.version value as the tag (tags have no v prefix). Find the path with git diff <bump>..HEAD --name-status -- engine plugins tools | grep '^A'. Only newly introduced classes/types are linked — not new members added to an existing class (e.g. Visible.isAlwaysVisible), and not types that already existed in a prior release.
• Be transparent about breaking changes and replacements. If an API replaces, renames, or removes another, state both sides.
• Thank external contributors inline, e.g. - thank you [@handle](https://github.com/handle). Find them with git log <bump>..HEAD --format='%an' and flag anyone who isn't the maintainer (Pandula Péter).
• A **Dependencies:** section lists notable bumped versions (Kotlin, Compose Multiplatform) as plain bullets, only when they actually changed this cycle (compare against gradle/libs.versions.toml).
• Professional, developer-focused voice. No marketing fluff, no emoji.