Menu
Guide the release process for rash, including version bumping, changelog updates, and creating release branches.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | release |
| description | Guide the release process for rash, including version bumping, changelog updates, and creating release branches. |
Provide step-by-step instructions for releasing a new version of rash, ensuring proper versioning, changelog updates, and release branch management.
Use this skill when asked to:
Before starting a release:
master branchUse Semantic Versioning (MAJOR.MINOR.PATCH). Determine the bump type by analyzing commits since the last release:
Bump MAJOR when:
BREAKING CHANGE: or ! (e.g., feat!: ...)Bump MINOR when:
feat: commits)Bump PATCH when:
fix: commits)docs: commits)refactor: commits)git log v$(sed -n 's/^version = "\(.*\)"/\1/p' ./Cargo.toml | head -n1)..HEAD --oneline! or BREAKING CHANGE: -> MAJORfeat: -> MINORfix:, docs:, refactor:, etc. -> PATCHEnsure you're on master with no uncommitted changes and up to date with origin:
git checkout master
git pull origin master
git status # Should show "nothing to commit, working tree clean"
If running in a shallow clone (e.g. CI with fetch-depth: 1), fetch full history and tags:
if git rev-parse --is-shallow-repository 2>/dev/null | grep -q "true"; then
git fetch --unshallow --quiet
fi
if [ -z "$(git tag -l)" ]; then
git fetch --tags --quiet
fi
Check that there are no unmerged commits:
git rev-list --count origin/master..HEAD
# Should output 0
If there are local commits not on origin/master, they must be merged first. The CHANGELOG template needs master commit IDs.
Get current version:
grep '^version =' Cargo.toml
Review commits since last release:
git log v<CURRENT_VERSION>..HEAD --oneline
Decide on MAJOR, MINOR, or PATCH bump based on the Version Decision Guide above.
Create a branch named release/v{NEW_VERSION}:
git checkout -b release/v<NEW_VERSION>
Example: git checkout -b release/v2.19.0
Edit Cargo.toml and update the version in the [workspace.package] section:
[workspace.package]
version = "<NEW_VERSION>"
The version is on line 7 of Cargo.toml.
Run make to update version in all workspace member Cargo.toml files and update the lock file:
make update-version
This command:
rash_core/Cargo.toml and rash_derive/Cargo.toml with the new versioncargo update -p rash_core -p rash_deriveGenerate the changelog using git-cliff:
make update-changelog
This runs: git cliff -t v<VERSION> -u -p CHANGELOG.md
The changelog will be automatically updated with commits since the last release, grouped by type (Added, Fixed, Documentation, etc.).
Stage and commit all changes:
git add .
VERSION=$(sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -n1)
git commit -m "release: Version $VERSION"
Push the release branch:
git push -u origin release/v<NEW_VERSION>
Create a pull request to merge into master.
After the PR is merged to master, tagging and releasing is done automatically by CI:
auto-tag.yml reads the new version from CHANGELOG.mdv<VERSION>The tag then triggers:
rust.yml: Builds, tests, publishes to crates.io, creates GitHub Releasedocker_images.yml: Builds/pushes Docker images to ghcr.ioaur-publish.yml: Publishes AUR packagesMonitor with:
gh run list --limit 5
Note: Do not manually create tags โ CI handles this automatically.
| Mistake | Why it's wrong | Fix |
|---|---|---|
| Manually editing CHANGELOG.md | git-cliff generates it from conventional commits | Use make update-changelog |
| Creating git tags manually | auto-tag.yml creates signed tags automatically | Just push to master |
| Releasing from a feature branch | Changelog generation needs master commit IDs | Checkout master first |
| Releasing with dirty working tree | Script will fail or produce incomplete release | Commit or stash changes first |
| Skipping the unshallow check | Shallow clones produce incomplete changelogs | Always check and unshallow if needed |
Forgetting make update-version after Cargo.toml edit | Version won't propagate to workspace members | Always run make update-version |
Using --amend on a commit | May amend the wrong parent commit after hook failures | Just commit again normally |
| Step | Command |
|---|---|
| Check current version | grep '^version =' Cargo.toml |
| View recent commits | git log v<CUR>..HEAD --oneline |
| Create branch | git checkout -b release/v<VER> |
| Update versions | make update-version |
| Update changelog | make update-changelog |
| Commit | git commit -m "release: Version <VER>" |
| Check shallow clone | git rev-parse --is-shallow-repository |
| Unshallow repo | git fetch --unshallow origin && git fetch --tags origin |
| Monitor CI | gh run list --limit 5 |
| Run release script | .ci/release.sh |
You're on a branch with unmerged commits. Switch to master and merge first.
The release script detected a shallow clone (e.g. CI with fetch-depth: 1). It automatically fetches full history and tags so git-cliff can generate a correct CHANGELOG. No action needed.
.ci/release.sh)git rev-list --count origin/master..HEAD)release/v<VERSION>[workspace.package]make update-versionmake update-changelogrelease: Version <VERSION>v<VERSION>