Release Management

Release Management Skill

Comprehensive release management workflow for TermIDE project that ensures code quality, version consistency, and proper changelog documentation before creating releases.

Platform note: agents that support extra frontmatter fields may add their own permission hints around this skill. Agents that do not support them should ignore unsupported fields and follow the workflow below. When interactive prompts or inline editing are unavailable, use the closest equivalent workflow the platform provides.

When to Use This Skill

Invoke this skill when you need to:

• Create a new release (patch/minor/major version bump)
• Recreate a failed release tag (after fixing CI/build issues)
• Update all version references across the project
• Generate changelog entries from git history and file changes
• Ensure code quality before tagging

Prerequisites

• Clean git working directory (or explicitly handle uncommitted changes)
• All tests passing locally
• No pending changes that should be in separate commits

Workflow Overview

This skill follows a comprehensive 12-step workflow:

1. Code Quality Checks - Run formatters, linters, tests, and build
2. Change Analysis - Analyze uncommitted changes, commits, and file states
3. Version Detection - Detect current version from multiple sources
4. Version Selection - Ask user for new version (patch/minor/major/custom/recreate)
5. File Updates - Update version in 12+ files across the project
6. Documentation Review - Prompt user to review and update docs if needed
7. Changelog Generation - Auto-generate CHANGELOG.md section from changes
8. Re-check Quality - Run quality checks again after file updates
9. Create Commit - Create conventional commit for release
10. Create Tag - Create annotated git tag
11. Push - Ask for confirmation before pushing to remote
12. Report - Show release URL and CI/CD status link

Step-by-Step Implementation

Step 1: Pre-Release Code Quality Checks

CRITICAL: These checks must pass before proceeding with release

Run these commands in sequence. If ANY fail, stop immediately and report errors:

# 1. Format check
cargo fmt --check

# 2. Clippy strict mode
cargo clippy -- -D warnings

# 3. Run test suite
cargo test

# 4. Release build check
cargo build --release

Error Handling:

• If cargo fmt --check fails: Show diffs and suggest running cargo fmt
• If cargo clippy fails: Show warnings/errors, suggest fixing before release
• If cargo test fails: Show failed tests, abort release
• If cargo build --release fails: Show build errors, abort release

Output to user:

🔍 Pre-Release Quality Checks
✅ Code formatting (cargo fmt --check)
✅ Linter checks (cargo clippy)
✅ Test suite (49 passed, 4 ignored)
✅ Release build

All quality checks passed! Proceeding with release...

Step 2: Analyze Changes for CHANGELOG

This is editorial work, not mechanical commit-parsing. The goal is a human-readable changelog, so the agent must understand what happened in the release, not just translate git log line-by-line.

Collect raw material from three sources, then synthesize it into themes (see "Synthesis" below before writing anything to CHANGELOG).

Source 1: Uncommitted Changes

git status --porcelain
git diff --stat

Parse output to detect:

• Modified files (M)
• Added files (A)
• Deleted files (D)
• Renamed files (R)

Source 2: Committed Changes Since Last Tag

# Get last tag
last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "")

# Get commits since tag (use full subjects + bodies, not just --oneline)
if [ -n "$last_tag" ]; then
    git log ${last_tag}..HEAD --no-decorate --pretty=fuller
else
    git log --no-decorate --pretty=fuller
fi

Conventional commit type is a hint for categorization, never the final word. Always cross-check with the actual diff before placing the change under Added / Changed / Fixed:

• feat: → usually Added
• fix: → usually Fixed
• docs: → Changed only if user-visible behavior or workflow changed
• refactor: / perf: → Changed only if user-observable; otherwise drop
• chore: / style: → almost never in changelog
• BREAKING CHANGE: (footer) → call out explicitly regardless of type

Source 3: File States at Each Commit

For each commit between tag and HEAD, check what actually changed in files:

# For each commit
git log ${last_tag}..HEAD --format="%H" | while read commit_hash; do
    git show --stat $commit_hash
done

This reveals:

• Which features were actually added (new files in src/panels/, etc.)
• Configuration changes (config.rs, constants.rs)
• Documentation updates (README.md, doc/*)

If a commit message says "feat: add X" but the diff only touches tests or unrelated files, trust the diff, not the message.

Synthesis — turn raw log into a coherent narrative

Git history contains a lot of noise the user will not want to read. Before writing the changelog, collapse the log into themes. A theme is a single user-visible change, possibly spanning many commits.

Drop entirely (do not surface to user as changelog candidates):

• Pure "WIP" / "checkpoint" / "save" commits with no standalone meaning.
• Typo fixes, formatting fixes, comment edits with no behavior change.
• Lint / clippy / fmt-only commits.
• Commits that were later fully reverted within the same release window.
• Dependency version bumps that don't change observable behavior (unless the bump is the release's headline).
• Iterative fixes-on-top-of-a-feature inside the same release — fold them into the feature's entry. The reader cares that "feature X works", not that it took three commits to land.
• Refactor-then-revert / "broke main, fixed main" pairs.
• Internal renames, file moves, module reorganizations with no API effect — unless they're a deliberate breaking change.

Collapse together (one changelog line per theme, not per commit):

• A feature plus its follow-up bugfixes from the same release window.
• A multi-step refactor that lands across N commits with one outcome.
• Translation updates for the same change in multiple languages (mention once, list affected locales if useful).

Keep, with rewording:

• User-visible behavior change → describe the effect on the user, not the implementation. "Migrated to XDG Base Directory Specification" is better than "feat(config): use dirs::config_dir() for state path".
• Bug fix → describe the bug as the user experienced it, not as the patch line in the diff. "Fixed crash when opening empty files" beats "fix: handle 0-length read in editor::load".
• Breaking change → say what breaks and what the user should do.

Pull from git show <hash> for context when a commit subject is cryptic but the diff is meaningful — write the changelog from the diff.

Verify the synthesis pass actually happened: if the resulting bullet count is roughly equal to the commit count, you almost certainly did not collapse anything. Re-read the log and merge follow-ups.

Output structure (raw analysis stage, before drafting CHANGELOG):

Changes Analysis:
==================

Uncommitted Changes:
- Modified: src/main.rs, Cargo.toml
- Added: CHANGELOG.md

Commits Since 0.2.0 (raw):
- 6d2e247 refactor: remove FileManager special handling
- 4e7c694 feat: migrate to XDG Base Directory Specification
- 6509fdb feat: implement session autosave
- a1b2c3d fix: typo in autosave
- d4e5f6a fix(autosave): debounce write
- 7890abc chore: clippy

Themes (after synthesis):
- XDG Base Directory Specification support  [4e7c694]
- Automatic session persistence with debounced writes  [6509fdb + d4e5f6a, typo and clippy folded in]
- FileManager is now a regular closable panel — BREAKING  [6d2e247]

Dropped as noise:
- a1b2c3d (typo, folded into autosave entry)
- 7890abc (clippy-only)

These themes, not the raw commit list, are what Step 7 turns into CHANGELOG entries.

Step 3: Detect Current Version

Check version in multiple files and detect inconsistencies:

# Cargo.toml (primary source)
cargo_version=$(grep '^version = ' Cargo.toml | head -1 | sed 's/version = "\(.*\)"/\1/')

# flake.nix
flake_version=$(grep 'version = ' flake.nix | head -1 | sed 's/.*version = "\(.*\)";/\1/')

# Last git tag
git_version=$(git describe --tags --abbrev=0 2>/dev/null || echo "none")

If versions match: Use that version as current.

If versions differ: Show table and ask user:

⚠️  Version Mismatch Detected:

File                     Version
-------------------------------------
Cargo.toml              0.2.0
flake.nix               0.1.5  ⚠️
Last git tag            0.2.0

Which version is correct as the current version?
1. 0.2.0 (Cargo.toml + git tag)
2. 0.1.5 (flake.nix)
3. Other (specify manually)

Use the platform's interactive prompt mechanism for this decision.

Step 4: Request New Version

Show current version and offer version bump options:

Current version: 0.2.0

Select release type:
1. patch (0.2.0 → 0.2.1) - Bug fixes, minor changes
2. minor (0.2.0 → 0.3.0) - New features, backwards compatible
3. major (0.2.0 → 1.0.0) - Breaking changes
4. custom - Enter specific version (e.g., 0.2.5)
5. recreate 0.2.0 - Recreate existing tag (for failed CI/CD)

Use the platform's interactive prompt mechanism with options:

• patch
• minor
• major
• custom
• recreate

For custom: Prompt for version string, validate format (X.Y.Z).

For recreate: Ask confirmation:

⚠️  Are you sure you want to recreate tag 0.2.0?
This will:
- Delete local tag 0.2.0
- Delete remote tag 0.2.0 (if pushed)
- Create new tag 0.2.0 with current HEAD

This is typically done when CI/CD failed and you fixed the issues.

Proceed? [yes/no]

Step 5: Update Version in All Files

Update version NEW_VERSION in these 10 files (plus Cargo.lock). Build the authoritative list first, so a file added since this skill was written is not missed:

git grep -c 'OLD_VERSION_ESCAPED' -- ':!CHANGELOG.md' ':!Cargo.lock'

(OLD_VERSION_ESCAPED is OLD_VERSION with the dots escaped, e.g. 0\.35\.0.) Every hit below is the release version itself, so a literal replace of all occurrences is safe in each file; review the grep output once in case a new file shows up with an unrelated match.

1. Cargo.toml

[workspace.package]
version = "NEW_VERSION"

Line 9 (under [workspace.package], which every crate inherits), exact match: version = "OLD_VERSION"

2. flake.nix (2 occurrences)

version = "NEW_VERSION";

One in packages.default (around line 84) and one in packages.termide-static (around line 117). Both are the exact match version = "OLD_VERSION"; — use replace_all=true.

3. README.md, README.ru.md, README.zh.md (23 occurrences each)

All occurrences are release asset file names in download URLs and commands:

termide-OLD_VERSION-x86_64-unknown-linux-gnu.tar.gz   (also musl, aarch64, apple-darwin)
termide-OLD_VERSION-x86_64-pc-windows-msvc.zip
termide_OLD_VERSION-1_amd64.deb
termide-OLD_VERSION-1.x86_64.rpm

Replace all occurrences of OLD_VERSION (note the .deb uses termide_, so a termide-VERSION- pattern alone would miss it). URLs go through releases/latest/download/, so there is no version in the URL path itself.

4. doc/en/installation.md, doc/ru/installation.md, doc/zh/installation.md (16 occurrences each)

Same asset names as the READMEs; replace all occurrences.

5. packaging/aur/PKGBUILD

pkgver=NEW_VERSION

Line 4, simple replacement. Reset pkgrel=1 if it was bumped.

6. packaging/aur/PKGBUILD-bin

pkgver=NEW_VERSION

Line 4, simple replacement. Reset pkgrel=1 if it was bumped.

7. Cargo.lock

The workspace crates' versions in Cargo.lock follow Cargo.toml, and the AUR build uses cargo fetch --locked, so the lock file must be committed with the new version. Refresh it after editing Cargo.toml:

cargo update --workspace

This touches only the workspace members' entries, not dependency versions.

Not bumped: packaging/crates-io-redirect/ is a standalone tombstone crate for the termide name on crates.io. Its version is unrelated to the release (it must exceed the crates.io maximum and is set only when that crate is republished by hand) — leave it alone. There is no Homebrew formula in the tree.

Batch Update Strategy: All files above can be updated in one pass (the version is not a substring of anything else in them):

git grep -l 'OLD_VERSION_ESCAPED' -- ':!CHANGELOG.md' ':!Cargo.lock' \
  | xargs sed -i '' 's/OLD_VERSION_ESCAPED/NEW_VERSION/g'   # GNU sed: -i without ''
cargo update --workspace

Or use the Edit tool with replace_all=true per file.

Verification: After updates, grep for the old version to ensure all replaced — this must print nothing:

git grep -n 'OLD_VERSION_ESCAPED' -- ':!CHANGELOG.md'

Cargo.lock is included on purpose: a leftover there means the workspace entries were not refreshed (unless a third-party dependency happens to share the old version number — check the name above any hit). Then confirm the new version landed everywhere with the expected counts (Cargo.toml 1, flake.nix 2, each README 23, each installation.md 16, each PKGBUILD 1):

git grep -c 'NEW_VERSION_ESCAPED' -- ':!CHANGELOG.md' ':!Cargo.lock'