| name | release-version |
|---|---|
| description | Use when releasing a new version - guides through version bump, changelog generation, commit grouping, tagging, and GitHub CI tracking. Triggers on "发布新版本", "release", "发版", or version release requests. |
Release Version Workflow
Overview
A complete release workflow for Gemini-Subtitle-Pro that handles version bumping, changelog generation from git history, grouped commits, tagging, and GitHub CI monitoring.
When to Use
- User says "发布新版本", "release", "发版"
- User requests a version release
- Before publishing a new release to GitHub
Workflow Steps
Step 0: Pre-flight Questions
Ask the user:
- Version number - What version to release? (e.g., 2.12.0)
- Pre-release? - Is this a pre-release version? (affects GitHub release settings)
Step 1: Check and Commit Uncommitted Changes
- Run
git statusto check for uncommitted changes - If changes exist: - Analyze the changes by topic/feature - Group related changes together - Create separate commits for each topic group - Use conventional commit messages (feat:, fix:, chore:, etc.)
Step 2: Generate Changelog
- Find the previous version tag:
bash
git describe --tags --abbrev=0
- Get all commits since last tag:
bash
git log <previous-tag>..HEAD --oneline
-
Read each commit's details to categorize: - Features - New functionality (feat:) - Fixes - Bug fixes (fix:) - Refactor - Code improvements (refactor:) - Chore - Maintenance tasks (chore:) - Documentation - Doc updates (docs:) - Performance - Performance improvements (perf:)
-
Update
CHANGELOG.md: - Add new version section at the top (after header) - Format:## [X.X.X] - YYYY-MM-DD(no 'v' prefix) - Group entries by category (Keep a Changelog format) -
Update
package.json: - Change"version": "X.X.X"to new version (no 'v' prefix)
Step 3: Commit Release Files
git add CHANGELOG.md package.json
git commit -m "Release vX.X.X"
Note: Commit message uses 'v' prefix, but version strings in files do not.
Step 4: Tag and Push
git tag vX.X.X
git push origin main
git push origin vX.X.X
Note: Tag uses 'v' prefix (e.g., v2.12.0).
Step 5: Monitor GitHub CI
- Track the GitHub Actions workflow:
bash
gh run list --workflow=release.yml --limit=1
gh run watch <run-id>
- Report build status to user: - Success: Provide release URL - Failure: Show error details
Quick Reference
| Step | Command | Purpose |
|---|---|---|
| Check status | git status |
Find uncommitted changes |
| Previous tag | git describe --tags --abbrev=0 |
Get last release tag |
| Commit log | git log <tag>..HEAD --oneline |
List changes since release |
| Create tag | git tag vX.X.X |
Create version tag |
| Push tag | git push origin vX.X.X |
Trigger CI build |
| Watch CI | gh run watch |
Monitor build progress |
Version Format Rules
| Location | Format | Example |
|---|---|---|
| Git tag | With 'v' prefix | v2.12.0 |
| Commit message | With 'v' prefix | Release v2.12.0 |
| CHANGELOG.md | No 'v' prefix | ## [2.12.0] - 2026-01-06 |
| package.json | No 'v' prefix | "version": "2.12.0" |
CHANGELOG Format
## [X.X.X] - YYYY-MM-DD
### Features
- **Component**: Description of new feature.
### Fixes
- **Component**: Description of bug fix.
### Refactor
- **Component**: Description of refactoring.
### Chore
- **Component**: Maintenance description.
Common Mistakes
| Mistake | Fix |
|---|---|
| Forgetting to push the tag | CI only triggers on tag push, not commit push |
| Wrong version in package.json | Version must match tag (without 'v' prefix) |
| Changelog in wrong position | New version goes after the header, before previous versions |
| Not grouping commits | Related changes should be in one commit for cleaner history |
| Inconsistent 'v' prefix | Tag and commit use 'v', files don't |
Pre-release Handling
For pre-release versions:
- Use version format:
X.X.X-beta.1,X.X.X-rc.1 - Tag format:
vX.X.X-beta.1 - Note: Current CI workflow sets
prerelease: false- may need manual adjustment in GitHub release