From 0cad9992e245d8dd74b415a2af8a850a38abca2a Mon Sep 17 00:00:00 2001 From: Woody Gilk Date: Tue, 6 Oct 2026 07:27:41 -0500 Subject: [PATCH] chore(ai): update version bump skill --- .agents/skills/version-bump/SKILL.md | 150 +++++++++++++++++++++++++++ .claude/skills/version-bump/SKILL.md | 99 ------------------ 2 files changed, 150 insertions(+), 99 deletions(-) create mode 100644 .agents/skills/version-bump/SKILL.md delete mode 100644 .claude/skills/version-bump/SKILL.md diff --git a/.agents/skills/version-bump/SKILL.md b/.agents/skills/version-bump/SKILL.md new file mode 100644 index 0000000..3e17d1f --- /dev/null +++ b/.agents/skills/version-bump/SKILL.md @@ -0,0 +1,150 @@ +--- +name: version-bump +description: Determines appropriate semantic version bumps based on changes. Use when deciding version numbers, evaluating breaking changes, or planning releases. Triggers on terms like "version", "semver", "breaking change", "major/minor/patch". +--- + +# Semantic Versioning Skill + +This skill helps determine appropriate version bumps following [Semantic Versioning](https://semver.org/). + +## Version Format + +``` +MAJOR.MINOR.PATCH +``` + +- **MAJOR**: Breaking changes +- **MINOR**: New features, backwards compatible +- **PATCH**: Bug fixes, backwards compatible + +_This format is referenced as `X.Y.Z` in this document._ + +## Version Bump Decision Tree + +### MAJOR (X.0.0) - Breaking Changes + +Bump MAJOR when you make incompatible API changes: + +- Removed public classes or methods +- Changed existing class namespaces +- Changed method signatures (parameters, return types) +- Changed default behavior that breaks existing usage + +### MINOR (0.X.0) - New Features + +Bump MINOR when you add functionality in a backwards compatible manner: + +- New classes or methods + +### PATCH (0.0.X) - Bug Fixes + +Bump PATCH when you make backwards compatible bug fixes: + +- Fix incorrect behavior +- Fix crashes or errors +- Performance improvements (no API changes) +- Internal refactoring (no behavior changes) +- Documentation fixes + +## Quick Reference + +| Change Type | Version Bump | +|----------------------------------|--------------| +| Breaking API change | MAJOR | +| Removed feature | MAJOR | +| New command/feature | MINOR | +| New CLI flag | MINOR | +| New provider/integration | MINOR | +| Bug fix | PATCH | +| Performance fix | PATCH | +| Documentation only | PATCH | +| Refactoring (no behavior change) | PATCH | + +## Pre-1.0 Versioning + +For versions < 1.0.0 (like this project): +- MINOR can include breaking changes +- PATCH is for bug fixes and small features +- More flexibility before reaching stability + +## Instructions + +1. Review all changes since last release: + `git log --oneline "$(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)"..HEAD` + The fallback covers the first release, when `git describe` has no tag to find + and would otherwise fail. +2. Check for breaking changes: + - Removed or renamed public APIs? + - Changed default behaviors? + - Incompatible configuration changes? +3. If breaking changes exist -> MAJOR bump +4. If new features exist -> MINOR bump +5. If only fixes/refactoring -> PATCH bump + +## Preparing the Release + +When `CHANGELOG.md` has a non-empty `## [Unreleased]` section, prepare the +release on a branch rather than committing to `main`: + +1. Create the branch from `main`: `chore/prepare-release-X.Y.Z` +2. Make the changelog and version commits there (see *Version Update Locations* below) +3. Push the branch and open a pull request +4. Stop here and wait for the pull request to be merged + +## Version Update Locations + +When bumping version, update `CHANGELOG.md`: + +1. Rename the accumulated `## [Unreleased]` heading to `## [X.Y.Z] - YYYY-MM-DD` +2. Add a fresh, empty `## [Unreleased]` heading above it, so the next change has + somewhere to go +3. Reconcile the section's contents with what actually shipped — entries written + while the work was in flight often still call a feature deferred that landed + later in the same cycle +4. Add a `[X.Y.Z]: https://github.com///releases/tag/X.Y.Z` link + definition at the bottom of CHANGELOG.md +5. Repoint the `[Unreleased]` link at the version just cut — + `.../compare/X.Y.Z...main`. It is the one comparison link the changelog + keeps, and leaving it behind makes the empty `[Unreleased]` section link to + a diff full of released work +6. Update `Cargo.toml` version. + +## Release Process + +Tag only when `## [Unreleased]` is empty — the top of the changelog is then the +version to release. Otherwise, create a pull request as described in +*Preparing the Release*. + +1. Check whether the tag already exists and which commit it points at. + Resolve it before comparing: `git rev-parse X.Y.Z^{commit}` for a local tag, + or `git ls-remote origin 'refs/tags/X.Y.Z*'` for the remote, where the `^{}` + line is the peeled commit of an annotated tag. Compare that commit with the + commit being released. + - No tag: continue to step 2. + - Remote tag at the release commit: a prior run already created and pushed + it, so skip to step 4. `--verify-tag` checks the remote tag, not a local + one. + - Local tag at the release commit, not yet on the remote: a prior run + created the signed tag but did not push it — skip to step 3 to push it. + - Tag pointing anywhere else: stop. Never move or force an existing tag. +2. Create a signed tag with no `v` prefix: `git tag -s X.Y.Z -m "X.Y.Z"` +3. Push the tag: `git push origin X.Y.Z` +4. Create the GitHub release from the changelog section for that version: + + ```sh + awk -v ver="X.Y.Z" ' + $0 ~ "^## \\[" ver "\\]" { inside=1; next } + inside && (/^## \[/ || /^\[[^]]+\]: /) { inside=0 } + inside { print } + ' CHANGELOG.md > /tmp/release-notes.md + + url=$(sed -n 's/^\[X\.Y\.Z\]: //p' CHANGELOG.md) + [ -n "$url" ] && printf '\n**Full Changelog**: %s\n' "$url" >> /tmp/release-notes.md + + gh release create X.Y.Z --title X.Y.Z --notes-file /tmp/release-notes.md --verify-tag + ``` + +5. Verify the release exists and is marked latest: `gh release list` + +Release notes are the changelog section verbatim, so the changelog stays the single source +of truth. `--verify-tag` fails the command rather than creating a tag that was never pushed. diff --git a/.claude/skills/version-bump/SKILL.md b/.claude/skills/version-bump/SKILL.md deleted file mode 100644 index d5656ce..0000000 --- a/.claude/skills/version-bump/SKILL.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -name: version-bump -description: Determines appropriate semantic version bumps based on changes. Use when deciding version numbers, evaluating breaking changes, or planning releases. Triggers on terms like "version", "semver", "breaking change", "major/minor/patch". ---- - -# Semantic Versioning Skill - -This skill helps determine appropriate version bumps following [Semantic Versioning](https://semver.org/). - -## Version Format - -``` -MAJOR.MINOR.PATCH -``` - -- **MAJOR**: Breaking changes -- **MINOR**: New features, backwards compatible -- **PATCH**: Bug fixes, backwards compatible - -## Version Bump Decision Tree - -### MAJOR (X.0.0) - Breaking Changes - -Bump MAJOR when you make incompatible API changes: - -- Removed public functions, methods, or types -- Changed function signatures (parameters, return types) -- Renamed public APIs -- Changed default behavior that breaks existing usage -- Removed CLI flags or changed their meaning -- Changed configuration file format incompatibly - -### MINOR (0.X.0) - New Features - -Bump MINOR when you add functionality in a backwards compatible manner: - -- New commands or subcommands -- New CLI flags -- New configuration options -- New output formats -- New integrations or providers - -### PATCH (0.0.X) - Bug Fixes - -Bump PATCH when you make backwards compatible bug fixes: - -- Fix incorrect behavior -- Fix crashes or errors -- Performance improvements (no API changes) -- Documentation fixes -- Internal refactoring (no behavior changes) - -## Quick Reference - -| Change Type | Version Bump | -|----------------------------------|--------------| -| Breaking API change | MAJOR | -| Removed feature | MAJOR | -| New command/feature | MINOR | -| New CLI flag | MINOR | -| New provider/integration | MINOR | -| Bug fix | PATCH | -| Performance fix | PATCH | -| Documentation only | PATCH | -| Refactoring (no behavior change) | PATCH | - -## Pre-1.0 Versioning - -For versions < 1.0.0 (like this project): -- MINOR can include breaking changes -- PATCH is for bug fixes and small features -- More flexibility before reaching stability - -## Instructions - -1. Review all changes since last release: - ```bash - git log --oneline $(git describe --tags --abbrev=0)..HEAD - ``` - -2. Check for breaking changes: - - Removed or renamed public APIs? - - Changed default behaviors? - - Incompatible configuration changes? - -3. If breaking changes exist -> MAJOR bump - -4. If new features exist -> MINOR bump - -5. If only fixes/refactoring -> PATCH bump - -## Version Update Locations - -When bumping version, update: - -1. **Cargo.toml** - `version = "X.Y.Z"` -2. **CHANGELOG.md** - Add `## [X.Y.Z] - YYYY-MM-DD` section -3. **Version links** - Update comparison URLs at bottom of CHANGELOG.md -4. **Unreleased link** - Update the `Unreleased` comparison URL at the bottom of CHANGELOG.md