release

name	release
description	Prepare and publish a new release. Use when the user asks to release, cut a release, or publish a new version.

Purpose

Release a new version of Timer CLI using the release script and CI pipeline.

When to use

Use this skill when:

• The user asks to release a new version
• The user asks to cut a release or publish
• The user asks to tag a new version

Prerequisites

Before releasing, verify:

1. Working tree is clean — no uncommitted changes
2. You are on master — releases only happen from master
3. Local master is up to date with origin/master
4. No commits ahead of origin/master (output of git rev-list --count origin/master..HEAD must be 0)
5. Repository is not a shallow clone — git-cliff needs full history for accurate changelogs

Check with:

git status --short
git rev-parse --abbrev-ref HEAD
git pull origin master
git rev-list --count origin/master..HEAD
git tag --sort=-creatordate | head -3
git log --oneline v<latest_tag>..HEAD

Version Decision Guide

Use Semantic Versioning (MAJOR.MINOR.PATCH). Determine the bump type by analyzing commits since the last release.

Major Version (X.0.0)

Bump MAJOR when:

• Breaking changes to CLI interface or arguments
• Breaking changes to output format
• Removal of previously supported time formats
• Commit message contains BREAKING CHANGE: or ! (e.g., feat!: ...)

Minor Version (0.X.0)

Bump MINOR when:

• New features added (feat: commits)
• New CLI options or subcommands
• New time format support
• Backward-compatible enhancements

Patch Version (0.0.X)

Bump PATCH when:

• Bug fixes (fix: commits)
• Documentation updates (docs: commits)
• Internal refactoring (refactor: commits)
• Dependency updates (chore(deps): commits)

Decision Process

1. Run: git log v<CURRENT_VERSION>..HEAD --oneline
2. Check commit messages for:
   • ! or BREAKING CHANGE: -> MAJOR
   • feat: -> MINOR
   • fix:, docs:, refactor:, etc. -> PATCH
3. If multiple types, use the highest precedence (MAJOR > MINOR > PATCH)

Release Process

Step 1: Verify Clean State

Ensure you're on master with no uncommitted changes, up to date with origin, and no commits ahead:

git checkout master
git pull origin master
git status  # Should show "nothing to commit, working tree clean"

Verify no commits ahead of origin/master:

git rev-list --count origin/master..HEAD  # Should output 0

Unshallow check — shallow clones produce incomplete changelogs:

git rev-parse --is-shallow-repository

If this outputs true, unshallow the repo before proceeding:

git fetch --unshallow origin
git fetch --tags origin

Step 2: Determine Version

1. Get current version:

   grep '^version =' Cargo.toml | head -1
   

2. Review commits since last release:

   git log v<CURRENT_VERSION>..HEAD --oneline
   

3. Decide on MAJOR, MINOR, or PATCH bump based on the Version Decision Guide above.

Step 3: Create Release Branch

git checkout -b release/v<NEW_VERSION>

Step 4: Update Version

Edit Cargo.toml and update the version:

version = "<NEW_VERSION>"

Step 5: Update Lock File

cargo update -p timer-cli

Step 6: Update Changelog

Generate the changelog using git-cliff:

make update-changelog

This runs: git cliff -t v<VERSION> -u -p CHANGELOG.md

The changelog is generated from conventional commits and grouped by type (Added, Fixed, Documentation, Build, Refactor, Styling, Testing, Chore). Release commits are excluded.

Step 7: Commit Changes

Stage and commit all changes:

git add .
VERSION=$(sed -n 's/^version = "\(.*\)"/\1/p' Cargo.toml | head -n1)
git commit -m "release: Version $VERSION"

Step 8: Push Branch and Create PR

git push -u origin release/v<NEW_VERSION>

Create a pull request to merge into master.

Step 9: After Merge

After the PR is merged to master, tagging and releasing is done automatically by CI:

1. auto-tag.yaml reads the new version from CHANGELOG.md
2. Creates a signed GPG tag v<VERSION>
3. Pushes the tag to GitHub

The tag then triggers:

• rust.yml: Builds for macOS and Linux, runs tests, publishes to crates.io, creates GitHub Release with changelog
• aur-publish.yml: Publishes AUR packages (timer-rs and timer-rs-bin)

Monitor with:

gh run list --limit 5

Note: Do not manually create tags — CI handles this automatically.

What NOT to Do

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.yaml 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
Using --amend on a commit	May amend the wrong parent commit after hook failures	Just commit again normally

Troubleshooting

"There are commits ahead of origin/master"

Merge or push them first before starting the release.

Shallow clone detected

git fetch --unshallow origin
git fetch --tags origin

git-cliff not installed

cargo install git-cliff

Auto-tag workflow didn't trigger

Ensure:

• The CHANGELOG.md has a new version entry as the first ## [v...] heading
• The tag doesn't already exist: git tag -l | grep <version>
• The PAT and GPG_PRIVATE_KEY secrets are configured in GitHub

Commit failed due to pre-commit hooks

Do NOT use --amend. Simply stage the changes and commit again:

git add .
git commit -m "release: Version <VERSION>"

Key Files

File	Role
Cargo.toml	Package version (single source of truth)
cliff.toml	git-cliff configuration for changelog generation
CHANGELOG.md	Generated changelog (auto-tag reads version from here)
.github/workflows/auto-tag.yaml	Creates signed GPG tag on push to master
.github/workflows/rust.yml	Builds, tests, publishes to crates.io and GitHub on tag
.github/workflows/aur-publish.yml	Publishes AUR packages on tag
Makefile	update-changelog target
.ci/release.sh	Full release script (can be run manually)

Checklist

• On master branch, clean working tree
• Pulled latest from origin/master
• No commits ahead of origin/master
• Repository is not a shallow clone (or has been unshallowed)
• Determined version bump type (MAJOR/MINOR/PATCH)
• Created release branch release/v<VERSION>
• Updated version in Cargo.toml
• Ran cargo update -p timer-cli
• Ran make update-changelog
• Committed with message release: Version <VERSION>
• Pushed and created PR
• After merge: CI automatically creates tag and release

Quick Reference

Step	Command
Check current version	grep '^version =' Cargo.toml | head -1
View recent commits	git log v<CUR>..HEAD --oneline
Check commits ahead	git rev-list --count origin/master..HEAD
Check shallow clone	git rev-parse --is-shallow-repository
Unshallow repo	git fetch --unshallow origin && git fetch --tags origin
Update lock file	cargo update -p timer-cli
Update changelog	make update-changelog
Commit	git commit -m "release: Version <VER>"
Monitor CI	gh run list --limit 5
Run release script	.ci/release.sh