Release Version

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

Version Format Rules

Changelog File Locations

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

Common Mistakes

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