Release Process

This document provides a comprehensive guide for the typstyle project release process, including version updates, changelog maintenance, build testing, and publishing steps.

Before starting a release, verify the current state of the repository:

# Check git status, ensure working directory is clean
git status

# Check current version
grep version Cargo.toml

# View recent commit history
git log --oneline -10

# Find the latest release tag
git describe --tags --abbrev=0

# View changes since last release (replace <latest-tag> with actual tag)
git log --oneline <latest-tag>..HEAD --no-merges

# Example: If the latest tag is v0.13.11, use:
# git log --oneline v0.13.11..HEAD --no-merges

# Check git status, ensure working directory is clean
git status

# Check current version
grep version Cargo.toml

# View recent commit history
git log --oneline -10

# Find the latest release tag
git describe --tags --abbrev=0

# View changes since last release (replace <latest-tag> with actual tag)
git log --oneline <latest-tag>..HEAD --no-merges

# Example: If the latest tag is v0.13.11, use:
# git log --oneline v0.13.11..HEAD --no-merges

Follow semantic versioning rules to determine the version number:

• Major (x.0.0): Breaking changes
• Minor (0.x.0): New features, backward compatible
• Patch (0.0.x): Bug fixes, backward compatible

Examine the actual code changes to understand what has been modified:

# View specific changes for each commit (crates directory only)
git show <commit-hash> -- crates/

# Or view all unreleased changes (replace <latest-tag> with actual tag)
git diff <latest-tag>..HEAD -- crates/

# View specific changes for each commit (crates directory only)
git show <commit-hash> -- crates/

# Or view all unreleased changes (replace <latest-tag> with actual tag)
git diff <latest-tag>..HEAD -- crates/

Classify the changes into appropriate categories:

• Feature: New functionality
• Bug fix: Error corrections
• Enhancement: Improvements
• Performance: Performance optimizations
• Refactor: Code refactoring
• CLI: Command-line related changes
• Breaking: Breaking changes

Edit the Cargo.tomlCargo.toml file to update the workspace version:

[workspace.package]
version = "<new-version>"  # New version number (e.g., "0.13.12")

[workspace.package]
version = "<new-version>"  # New version number (e.g., "0.13.12")

Also update the workspace dependencies:

[workspace.dependencies]
typstyle-core = { path = "crates/typstyle-core", version = "<new-version>" }
typstyle = { path = "crates/typstyle", version = "<new-version>" }
typstyle-wasm = { path = "crates/typstyle-wasm", version = "<new-version>" }

[workspace.dependencies]
typstyle-core = { path = "crates/typstyle-core", version = "<new-version>" }
typstyle = { path = "crates/typstyle", version = "<new-version>" }
typstyle-wasm = { path = "crates/typstyle-wasm", version = "<new-version>" }

Add the new version at the top of the CHANGELOG.mdCHANGELOG.md file:

## v<new-version> - [YYYY-MM-DD]

- Feature(CLI): Specific feature description
- Bug fix: Specific fix description
- Enhancement: Specific improvement description

## v<new-version> - [YYYY-MM-DD]

- Feature(CLI): Specific feature description
- Bug fix: Specific fix description
- Enhancement: Specific improvement description

When writing changelog entries, follow these guidelines:

• Use present tense to describe changes
• Include specific examples when applicable
• Mark breaking changes clearly
• Sort by importance (Feature > Enhancement > Bug fix)
• Add CLI-related tags for command-line changes
• Include related issue/PR links when applicable

Use these standard categories for changelog entries:

• Feature: New features
• Feature(CLI): Command-line new features
• Bug fix: Error corrections
• Enhancement: Feature improvements
• Performance: Performance optimizations
• (breaking): Breaking change marker

Commit the version and changelog updates:

# Add changed files
git add Cargo.toml Cargo.lock CHANGELOG.md

# Commit changes
git commit -m "chore: update version to v<new-version> and update changelog"

# Add changed files
git add Cargo.toml Cargo.lock CHANGELOG.md

# Commit changes
git commit -m "chore: update version to v<new-version> and update changelog"

Create and push the version tag:

# Create version tag with signature
git tag -s v<new-version>

# Push to remote repository
git push origin master
git push origin v<new-version>

# Create version tag with signature
git tag -s v<new-version>

# Push to remote repository
git push origin master
git push origin v<new-version>

After pushing:

• Check GitHub Actions or other CI systems
• Ensure all tests pass
• Ensure build succeeds

CI usually automatically detects new tags and publishes to:

• crates.io (Rust crates)
• npm (if WASM package exists)
• GitHub Releases

After a successful release:

• Check if project homepage is updated
• Update version references in related documentation
• Notify community about new release

Please confirm the following items before release:

• ☐ Check git status, ensure working directory is clean
• ☐ Analyze all changes since last release
• ☐ Determine appropriate new version number
• ☐ Update version number in Cargo.tomlCargo.toml
• ☐ Update CHANGELOG.mdCHANGELOG.md with new version entry
• ☐ Build project to ensure no errors
• ☐ Run tests (optional but recommended)
• ☐ Commit version updates and changelog
• ☐ Create and push version tag
• ☐ Monitor CI/CD process
• ☐ Verify successful release
• ☐ Update related documentation