Release Version Workflow

Overview

A complete release workflow for MioSub 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:

1. Version number - What version to release? (e.g., 2.12.0)
2. Pre-release? - Is this a pre-release version? (affects GitHub release settings)

Step 1: Check and Commit Uncommitted Changes

1. Run git status to check for uncommitted changes
2. 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

1. Find the previous version tag:

   git describe --tags --abbrev=0
   

2. Get all commits since last tag:

   git log <previous-tag>..HEAD --oneline
   

3. 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:)

   Exclude from changelog (internal/infrastructure changes not relevant to users):

   • Error tracking changes (Sentry integration, error reporting)
   • Analytics/telemetry service modifications
   • Internal monitoring or logging infrastructure

4. Update changelog files in the documentation site (bilingual):

   English (docs/content/docs/en/changelog.mdx):

   • Add new version section after the frontmatter and intro paragraph
   • Format: ## [X.X.X] - YYYY-MM-DD (no 'v' prefix)
   • Group entries by category (Keep a Changelog format)
   • Use English descriptions

   Chinese (docs/content/docs/zh/changelog.mdx):

   • Mirror the same structure as English
   • Translate all descriptions to Chinese
   • Use Chinese category names: 新功能, 修复, 重构, 杂项, 文档, 性能

5. Update package.json:

   • Change "version": "X.X.X" to new version (no 'v' prefix)

Step 3: Commit Release Files

git add docs/content/docs/en/changelog.mdx docs/content/docs/zh/changelog.mdx 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

1. Track the GitHub Actions workflow:

   gh run list --workflow=release.yml --limit=1
   gh run watch <run-id>
   

2. 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.mdx (en/zh)	No 'v' prefix	## [2.12.0] - 2026-01-06
package.json	No 'v' prefix	"version": "2.12.0"

Changelog File Locations

Language	Path
English	docs/content/docs/en/changelog.mdx
Chinese	docs/content/docs/zh/changelog.mdx

CHANGELOG Format (English)

## [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.

CHANGELOG Format (Chinese)

## [X.X.X] - YYYY-MM-DD

### 新功能

- **组件名**: 新功能描述。

### 修复

- **组件名**: Bug 修复描述。

### 重构

- **组件名**: 重构描述。

### 杂项

- **组件名**: 维护工作描述。

Category Name Mapping

English	Chinese
Features	新功能
Fixes	修复
Refactor	重构
Chore	杂项
Documentation	文档
Performance	性能
Highlights	亮点
Improvements	改进
Other Changes	其他变更

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 frontmatter, 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
Missing Chinese translation	Both en and zh changelog files must be updated together
Mismatched category translations	Use the Category Name Mapping table for consistency

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