suxin2017/lynx-proxy/release

Lynx Proxy Release Process

When to Use

• User asks to publish a new version / 发布版本
• User asks to bump version / 升级版本
• User asks to trigger CI build / 触发流水线构建
• User asks to create a release / 创建 Release

Prerequisites

• Working directory: /Users/wx/codes/lynx-proxy
• Rust toolchain: stable (rustfmt + clippy)
• Installed tools: cargo-release, git-cliff, task
• UI dependencies: npm ci in ui/
• Git: clean working tree (no uncommitted changes)
• All tests pass and linter is clean (see step 2)

Release Procedure

1. Determine Version

Check current version from Cargo.toml:

workspace.package.version

Determine the new version based on changes:

• patch (0.8.4 → 0.8.5): Bug fixes only
• minor (0.8.4 → 0.9.0): New features, backward compatible
• major (0.8.4 → 1.0.0): Breaking changes

2. Run Tests & Lint

⚠️ Never release without passing tests!

# Run all workspace tests
cargo test --workspace
 
# Run clippy linter (deny warnings)
cargo clippy --all-targets --all-features -- -D warnings
 
# Check formatting
cargo fmt --all -- --check

Or use the Taskfile:

task lint
task test

3. Update CHANGELOG

Update CHANGELOG.md:

• Add a new section ## [<version>] - <YYYY-MM-DD>
• Group changes under conventional commit categories:
• ### 🚀 Features
• ### 🐛 Bug Fixes
• ### ♻️ Refactor
• ### 📚 Documentation
• ### 🧪 Testing
• ### ⚙️ Miscellaneous Tasks
• Use format: - *(<scope>)* <description>

Alternatively, generate from git history:

git-cliff --unreleased --tag v<version> --prepend CHANGELOG.md

4. Bump Version (Root Cargo.toml)

Update the version field in Cargo.toml under [workspace.package]:

version = "<new_version>"

⚠️ All sub-crates use version.workspace = true, so only the root Cargo.toml needs updating.

5. Build UI Assets

cd /Users/wx/codes/lynx-proxy && task build-ui

This generates the Vue.js frontend into crates/lynx-cli/assets/.

6. Export Rules Schema

cargo run -q -p lynx-cli -- rules schema export --out schemas/rules-export.schema.json

7. Commit & Tag

git add -A
git commit -m "chore(release): v<version>"
git tag v<version>

8. Push to GitHub

git push origin main
git push origin v<version>

This triggers the Release GitHub Actions workflow (.github/workflows/release.yml), which:

1. Builds the UI assets
2. Runs cargo-dist to build binaries for:

• aarch64-apple-darwin (macOS ARM)
• x86_64-unknown-linux-gnu (Linux x86_64)
• x86_64-pc-windows-msvc (Windows x86_64)

1. Creates a GitHub Release with artifacts and installer scripts

9. (Optional) Quick Release with cargo-release

For a fully automated flow:

# Patch release
cargo release patch --execute
 
# Minor release
cargo release minor --execute
 
# Major release  
cargo release major --execute

This uses the config in release.toml:

• Pre-release hook: task build-ui
• Pre-tag hook: exports rules schema
• No crates.io publish (publish = false)
• Auto-push to git

Important Notes

• Tests are mandatory: The Taskfile release tasks (release-patch, release-minor, release-alpha) all declare test as a dependency — they will refuse to run if tests fail.
• No crates.io publish: release.toml sets publish = false. GitHub Actions handles binary distribution.
• Tag format: v<semver> (e.g., v0.8.4), triggers .github/workflows/release.yml.
• Changelog convention: Keep CHANGELOG.md with ## [<version>] - <YYYY-MM-DD> headers.
• Commit convention: Use conventional commits (feat:, fix:, chore:, etc.) for changelog generation.
• After release: Verify the GitHub Actions workflow at https://github.com/xin2017338/lynx-proxy/actions.

Rollback

If something goes wrong after pushing:

# Delete remote tag
git push --delete origin v<version>
 
# Delete local tag
git tag -d v<version>
 
# Revert commit
git revert HEAD
git push origin main