Release Guide
This guide describes how to release a new version of Suzent. The process is automated using GitHub Actions, but requires a manual version bump and tagging.
1. Bump Version
We use a helper script to consistently update the version number across all necessary files (package.json, Cargo.toml, pyproject.toml, etc.).
Usage
Run the bump_version.py script from the root directory:
# Bump patch version (e.g., 0.1.0 -> 0.1.1)
python scripts/bump_version.py patch
# Bump minor version (e.g., 0.1.0 -> 0.2.0)
python scripts/bump_version.py minor
# Bump major version (e.g., 0.1.0 -> 1.0.0)
python scripts/bump_version.py major
# Set specific version
python scripts/bump_version.py 1.2.3
The script will automatically updates:
src-tauri/tauri.conf.jsonsrc-tauri/package.jsonsrc-tauri/Cargo.tomlfrontend/package.jsonpyproject.toml
At the end, it will output the git commands you need to run to commit the changes.
2. Update Changelog
Before committing and tagging, add an entry to CHANGELOG.md for the new version. Follow the Keep a Changelog format:
## [v0.2.3] - 2026-02-03
### 🚀 Added
- **Feature**: Description of new features.
### ⚡ Changed
- **Component**: Description of changes.
### 🐛 Fixed
- **Bug**: Description of bug fixes.
[!IMPORTANT] The version in the changelog header (e.g.,
[v0.2.3]) must match the git tag exactly. Release notes are automatically extracted from this section.
3. Run Pre-commit Hooks
Before committing the version bump and changelog, ensure all code is properly formatted and linted. The CI workflow runs ruff check . and will fail if there are linting issues.
# Run pre-commit hooks on all files
pre-commit run --all-files
# Or manually run ruff
ruff check . --fix
ruff format .
[!TIP] Install pre-commit hooks to run automatically before each commit:
pre-commit install
4. Update Lock Files
After bumping the version, the lock files need to be regenerated to reflect the new version numbers:
# Update npm lock files
cd frontend && npm install && cd ..
cd src-tauri && npm install && cd ..
# Update Cargo.lock (will be done automatically on next cargo build)
5. Trigger Release (commit & tag)
After bumping the version, updating lock files, updating the changelog, and running pre-commit, commit the changes and create a git tag. The GitHub Action workflow listens for tags starting with v (e.g., v0.1.1).
# 1. Commit the version bump, lock files, and changelog
git add .
git commit -m "chore: bump version to 0.1.1"
# 2. Create a tag
git tag v0.1.1
# 3. Push to GitHub
git push && git push --tags
6. Automated Build & Release
Once the tag is pushed, the Build Desktop Apps workflow will automatically trigger. It performs the following steps:
- Extracts Release Notes: Reads the changelog entry for the tagged version from
CHANGELOG.md. - Bundles Python Backend: Downloads standalone Python + uv, builds suzent wheel into
src-tauri/resources/. - Builds Frontend: Builds the React frontend.
- Builds Desktop App: Bundles everything into a Tauri application.
- Windows:
.msi - macOS:
.dmg(Intel & Apple Silicon) - Linux:
.AppImage/.deb(Ubuntu)
- Windows:
- Publishes Release: Creates a GitHub Release with:
- Release notes from the changelog (fully automated!)
- All platform artifacts attached
7. Verify Release
- Go to the GitHub Releases page.
- Verify the release was created with the correct version and release notes.
- Download and test the artifacts if needed.
Troubleshooting
Pipeline Fails
If you forgot to run pre-commit hooks or want to revert the release:
-
Delete the problematic tag:
# Delete locally
git tag -d v0.2.2 # Replace with your tag version
# Delete remotely
git push origin :refs/tags/v0.2.2 -
Recreate the tag:
# Create the tag on the latest commit (with precommit fixes)
git tag v0.2.2
# Push everything
git push && git push --tags
Missing Changelog Entry
If the workflow fails because the changelog entry is missing or doesn't match the tag version:
- Ensure there's an entry in
CHANGELOG.mdwith the exact version matching your tag. - The header must use the format:
## [v0.2.2] - 2026-02-02(version must match the git tag). - Follow steps 3-4 above to delete and recreate the tag after updating the changelog.