This document describes how releases are created for Auto Claude.
Auto Claude uses an automated release pipeline that ensures releases are only published after all builds succeed. This prevents version mismatches between documentation and actual releases.
┌─────────────────────────────────────────────────────────────────────────────┐
│ RELEASE FLOW │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ develop branch main branch │
│ ────────────── ─────────── │
│ │ │ │
│ │ 1. bump-version.js │ │
│ │ (creates commit) │ │
│ │ │ │
│ ▼ │ │
│ ┌─────────┐ │ │
│ │ v2.8.0 │ 2. Create PR │ │
│ │ commit │ ────────────────────► │ │
│ └─────────┘ │ │
│ │ │
│ 3. Merge PR ▼ │
│ ┌──────────┐ │
│ │ v2.8.0 │ │
│ │ on main │ │
│ └────┬─────┘ │
│ │ │
│ ┌───────────────────┴───────────────────┐ │
│ │ GitHub Actions (automatic) │ │
│ ├───────────────────────────────────────┤ │
│ │ 4. prepare-release.yml │ │
│ │ - Detects version > latest tag │ │
│ │ - Creates tag v2.8.0 │ │
│ │ │ │
│ │ 5. release.yml (triggered by tag) │ │
│ │ - Builds macOS (Intel + ARM) │ │
│ │ - Builds Windows │ │
│ │ - Builds Linux │ │
│ │ - Generates changelog │ │
│ │ - Creates GitHub release │ │
│ │ - Updates README │ │
│ └───────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
On your development branch (typically develop or a feature branch):
# Navigate to project root
cd /path/to/auto-claude
# Bump version (choose one)
node scripts/bump-version.js patch # 2.7.1 -> 2.7.2 (bug fixes)
node scripts/bump-version.js minor # 2.7.1 -> 2.8.0 (new features)
node scripts/bump-version.js major # 2.7.1 -> 3.0.0 (breaking changes)
node scripts/bump-version.js 2.8.0 # Set specific versionThis will:
- Update
apps/frontend/package.json - Update
package.json(root) - Update
apps/backend/__init__.py - Check if
CHANGELOG.mdhas an entry for the new version (warns if missing) - Create a commit with message
chore: bump version to X.Y.Z
IMPORTANT: The release will fail if CHANGELOG.md doesn't have an entry for the new version.
Add release notes to CHANGELOG.md at the top of the file:
## 2.8.0 - Your Release Title
### ✨ New Features
- Feature description
### 🛠️ Improvements
- Improvement description
### 🐛 Bug Fixes
- Fix description
---Then amend the version bump commit:
git add CHANGELOG.md
git commit --amend --no-edit# Push your branch
git push origin your-branch
# Create PR to main (via GitHub UI or gh CLI)
gh pr create --base main --title "Release v2.8.0"Once the PR is approved and merged to main, GitHub Actions will automatically:
- Detect the version bump (
prepare-release.yml) - Validate CHANGELOG.md has an entry for the new version (FAILS if missing)
- Extract release notes from CHANGELOG.md
- Create a git tag (e.g.,
v2.8.0) - Trigger the release workflow (
release.yml) - Build binaries for all platforms:
- macOS Intel (x64) - code signed & notarized
- macOS Apple Silicon (arm64) - code signed & notarized
- Windows (NSIS installer) - code signed
- Linux (AppImage + .deb)
- Scan binaries with VirusTotal
- Create GitHub release with release notes from CHANGELOG.md
- Update README with new version badge and download links
After merging, check:
- GitHub Actions - ensure all workflows pass
- Releases - verify release was created
- README - confirm version updated
We follow Semantic Versioning:
- MAJOR (X.0.0): Breaking changes, incompatible API changes
- MINOR (0.X.0): New features, backwards compatible
- PATCH (0.0.X): Bug fixes, backwards compatible
Release notes are managed in CHANGELOG.md and used for GitHub releases.
Each version entry in CHANGELOG.md should follow this format:
## X.Y.Z - Release Title
### ✨ New Features
- Feature description with context
### 🛠️ Improvements
- Improvement description
### 🐛 Bug Fixes
- Fix description
---The release workflow validates that CHANGELOG.md has an entry for the version being released:
- If the entry is missing, the release is blocked with a clear error message
- If the entry exists, its content is used for the GitHub release notes
- Be specific: Instead of "Fixed bug", write "Fixed crash when opening large files"
- Group by impact: Features first, then improvements, then fixes
- Credit contributors: Mention contributors for significant changes
- Link issues: Reference GitHub issues where relevant (e.g., "Fixes #123")
| Workflow | Trigger | Purpose |
|---|---|---|
prepare-release.yml |
Push to main |
Detects version bump, validates CHANGELOG.md, creates tag |
release.yml |
Tag v* pushed |
Builds binaries, extracts changelog, creates release |
update-readme (in release.yml) |
After release | Updates README with new version |
-
Check if version in
package.jsonis greater than latest tag:git tag -l 'v*' --sort=-version:refname | head -1 cat apps/frontend/package.json | grep version
-
Ensure the merge commit touched
package.json:git diff HEAD~1 --name-only | grep package.json
If you see "CHANGELOG VALIDATION FAILED" in the workflow:
- The
prepare-release.ymlworkflow validated thatCHANGELOG.mddoesn't have an entry for the new version - Fix: Add an entry to
CHANGELOG.mdwith the format## X.Y.Z - Title - Commit and push the changelog update
- The workflow will automatically retry when the changes are pushed to
main
# Add changelog entry, then:
git add CHANGELOG.md
git commit -m "docs: add changelog for vX.Y.Z"
git push origin main- The release won't be published if builds fail
- Fix the issue and create a new patch version
- Don't reuse failed version numbers
- README is only updated after successful release
- If release failed, README keeps the previous version (this is intentional)
- Once you successfully release, README will update automatically
In rare cases where you need to bypass the automated flow:
# Create tag manually (NOT RECOMMENDED)
git tag -a v2.8.0 -m "Release v2.8.0"
git push origin v2.8.0
# This will trigger release.yml directlyWarning: Only do this if you're certain the version in package.json matches the tag.
- All macOS binaries are code signed with Apple Developer certificate
- All macOS binaries are notarized by Apple
- Windows binaries are code signed
- All binaries are scanned with VirusTotal
- SHA256 checksums are generated for all artifacts