| name | generate-release |
| description | Use when creating a new ktools release version — runs tests, updates dependency metadata and docs, generates changelog from commit history, tags, pushes, and updates GitHub release |
Generate Release
Automates the ktools release process. Accepts a version name (e.g., v0.4.0) as input.
Input
- Version (required): Semver string prefixed with
v (e.g., v0.4.0)
Prerequisites
- On the
main branch with a clean working tree
gh CLI authenticated- JDK 17 available
Steps
Follow each step in order. Stop immediately if any step fails.
1. Validate version format
Verify the version matches v<major>.<minor>.<patch> (e.g., v0.4.0).
Verify the tag does not already exist:
git tag -l <version>
If it returns output, the tag exists — stop and warn the user.
2. Run tests
./gradlew allTests
If tests fail, stop. Report which tests failed.
3. Update libraries and licenses JSON
./gradlew exportLibraryDefinitions
cp build/generated/aboutLibraries/librariesandlicenses.json src/nativeMain/resources/librariesandlicenses.json
Check if the file changed:
git diff --exit-code src/nativeMain/resources/librariesandlicenses.json
If changed (exit code 1), commit:
git add src/nativeMain/resources/librariesandlicenses.json
git commit -m "chore: update librariesandlicenses.json for <version>"
If unchanged (exit code 0), skip the commit.
4. Trigger dokka docs deployment
The dokka docs are generated and deployed via the docs.yml workflow (not committed to the repo). Trigger it:
gh workflow run docs.yml
This runs asynchronously — no need to wait for it to complete before continuing.
5. Generate changelog
Get the previous tag:
git describe --tags --abbrev=0
Generate the changelog, excluding docs/superpowers commits:
git log <previous-tag>..HEAD --oneline -- . ':!docs/superpowers'
Format each line as a markdown list item:
- <commit hash> <commit subject>
Save the full changelog text for use in steps 6 and 8.
6. Create annotated tag
git tag -a <version> -m "<changelog>"
Use the changelog from step 5 as the tag annotation.
7. Push commits and tag
git push && git push --tags
This triggers the release.yml CI workflow.
8. Wait for CI
Poll the release workflow until it completes:
gh run list --workflow=release.yml --limit=1 --json status,conclusion
Re-check every 60 seconds until status is completed. Then check conclusion — if it is not success, report the failure and stop.
9. Update GitHub release body
Verify the release exists first:
gh release view <version>
If the release does not exist yet (CI may still be finalizing), wait and retry.
Then update the release body:
gh release edit <version> --notes "<changelog>"
Use the same changelog from step 5. This ensures the changelog appears in both the tag annotation and the GitHub release page.
Error Recovery
| Failure | What to do |
|---|
| Tests fail (step 2) | Fix tests, re-run from step 1 |
| Gradle task fails (step 3) | Check Gradle output, fix, re-run the failed step |
| Docs workflow fails (step 4) | Investigate via gh run list --workflow=docs.yml --limit=1, re-trigger with gh workflow run docs.yml |
| Tag already exists (step 1) | User must choose a different version or delete the existing tag |
| Push fails (step 7) | Check remote status, resolve conflicts, retry push |
| CI fails (step 8) | Investigate the workflow run via gh run view, fix and re-tag if needed |
| Release edit fails (step 9) | Retry manually: gh release edit <version> --notes "<changelog>" |
