jellytau/docs/release-checklist.md

Release Checklist

Quick reference for creating a JellyTau release.

Pre-Release (1-2 days before)

• Code is on master/main branch
• All feature branches are merged and tested
• No failing tests locally: bun run test and bun run test:rust
• Requirement traceability check passes: bun run traces:json
• Type checking passes: bun run check

Update Version (Day before)

• Decide on version number (semantic versioning)

  • Example: v1.2.0 (major.minor.patch)
  • Example: v1.0.0-rc1 (release candidate)
  • Example: v1.0.0-beta (beta)

• Update version in files:

  # Check these files for version numbers
  cat package.json | grep version
  cat src-tauri/tauri.conf.json | grep version
  cat src-tauri/Cargo.toml | grep version
  

• Update CHANGELOG.md:

  • Add section for new version
  • List all features added
  • List all bugs fixed
  • List breaking changes (if any)
  • Add upgrade instructions (if needed)
  • Format: Markdown with clear sections

• Update README.md:

  • Update any version references
  • Update feature list if applicable
  • Update requirements if changed

• Commit changes:

  git add .
  git commit -m "Bump version to v1.2.0"
  git push origin master
  

Final Check Before Release

• Run full test suite:

  bun run test          # Frontend tests
  bun run test:rust     # Rust tests
  bun run check         # Type checking
  

• Build locally (optional but recommended):

  # Test Linux build
  bun run tauri build
  
  # Test Android build
  bun run tauri android build
  

• No uncommitted changes:

  git status  # Should show clean working directory
  

Release (Tag & Push)

# 1. Create annotated tag with release notes
git tag -a v1.2.0 -m "Release version 1.2.0

Features:
- New feature 1
- New feature 2

Fixes:
- Fixed bug 1
- Fixed bug 2

Improvements:
- Performance improvement 1
- UI improvement 1

Breaking Changes:
- None (or list if applicable)

Migration:
- No action required (or include steps if applicable)"

# 2. Push tag to trigger workflow
git push origin v1.2.0

# 3. Monitor in Gitea Actions
# Go to Actions tab and watch the workflow run

During Release (While Workflow Runs)

• Watch workflow progress in Gitea Actions
• Monitor for test failures
• Monitor for build failures
• Check build logs if any step fails

After Release (Workflow Complete)

• Download artifacts from release page:

  • JellyTau_*.AppImage (Linux)
  • JellyTau_*.deb (Linux)
  • JellyTau-*.rpm (Linux)
  • jellytau-release.apk (Android)
  • jellytau-release.aab (Android)

• Basic testing of artifacts:

  • Linux AppImage runs
  • Linux DEB installs and runs
  • Android APK installs (via adb or sideload)

• Verify release page:

  • Title is correct: "JellyTau vX.Y.Z"
  • Release notes are formatted correctly
  • All artifacts are uploaded
  • Release type is correct (prerelease vs release)

• Verify integrity metadata (DR-216):

  • SHA256SUMS is present, and sha256sum -c SHA256SUMS passes in the directory you downloaded into
  • SBOM files are present (*.cdx.json, frontend-dependencies.txt)

• Verify the update path (DR-217) — this is the step that catches a broken updater before users hit it, because a bad manifest fails only on their machine:

  • latest.json is live and names this version: curl -s https://gitea.tourolle.paris/dtourolle/jellytau/raw/branch/updater/latest.json | jq .version
  • Both platform entries carry a non-empty signature
  • The .AppImage.tar.gz, its .sig, and the NSIS .sig are among the release assets — the manifest points at them
  • Install the previous release, launch it, and use Settings → Updates: it should offer this version, install it, and relaunch
  • On Android, Settings → Updates offers the releases page rather than an install button (the updater plugin is not compiled for that target)

• Announce release:

  • Post to relevant channels/communities
  • Update website/docs
  • Tag contributors if applicable

Rollback (If Issues Found)

If critical issues are found after release:

# Option 1: Delete tag locally and remotely
git tag -d v1.2.0
git push origin :refs/tags/v1.2.0

# Option 2: Mark as prerelease in release page
# Then plan immediate patch release (v1.2.1)

# Option 3: Create hotfix branch and release v1.2.1
git checkout -b hotfix/v1.2.1
# Fix issues
git commit -m "Fix critical issue"
git tag v1.2.1
git push origin hotfix/v1.2.1 v1.2.1

Version Examples

Major Release

v2.0.0 - Major version bump
- Significant new features
- Breaking API changes
- Major UI redesign

Minor Release

v1.2.0 - Feature release
- New features
- Backward compatible
- Bug fixes

Patch Release

v1.1.1 - Bug fix/patch
- Bug fixes only
- No new features
- Backward compatible

Pre-releases

v1.2.0-alpha    - Early development
v1.2.0-beta     - Late development, feature complete
v1.2.0-rc1      - Release candidate, minimal fixes only

File Locations

Key files for versioning:

• package.json - Frontend version
• src-tauri/tauri.conf.json - Tauri config version
• src-tauri/Cargo.toml - Rust version
• CHANGELOG.md - Release history
• README.md - Project documentation

Troubleshooting

Tests Fail Before Release

1. Don't push tag yet
2. Fix failing tests locally
3. Push fixes to master
4. Re-run test suite
5. Then tag and push

Build Fails in CI

1. Check detailed logs in Gitea Actions
2. Fix issue locally
3. Delete tag: git tag -d v1.2.0 && git push origin :refs/tags/v1.2.0
4. Push fix to master
5. Create new tag with fix

Release Already Exists

1. If workflow runs twice, artifacts may conflict
2. Check release page
3. If duplicates exist, delete and re-release

Artifacts Missing

1. Check build logs for errors
2. Verify platform-specific dependencies
3. Delete tag and retry after fixes

Performance Tips

• Tests: ~5-10 minutes
• Linux build: ~10-15 minutes
• Android build: ~15-20 minutes
• Total release time: ~30-45 minutes

First build takes longer (cache warming). Subsequent releases are faster due to caching.

Template: Release Notes

## 🎉 JellyTau vX.Y.Z

### ✨ Features
- New feature 1
- New feature 2

### 🐛 Bug Fixes
- Fixed issue #123
- Fixed issue #456

### 🚀 Performance
- Improvement 1
- Improvement 2

### 📱 Downloads
- [Linux AppImage](#) - Run on any Linux
- [Linux DEB](#) - Install on Ubuntu/Debian
- [Android APK](#) - Install on Android devices
- [Android AAB](#) - For Google Play Store

### 📋 Requirements
**Linux:** 64-bit, GLIBC 2.29+
**Android:** 8.0+

### 🔗 Links
- [Changelog](https://gitea.tourolle.paris/dtourolle/jellytau/src/branch/master/CHANGELOG.md)
- [Issues](https://gitea.tourolle.paris/dtourolle/jellytau/issues)

---
Built with Tauri, SvelteKit, and Rust 🦀

Quick Commands

# View existing tags
git tag -l

# Create release locally (dry run)
git tag -a v1.2.0 -m "Release v1.2.0" --dry-run

# List commits since last tag
git log v1.1.0..HEAD --oneline

# Show tag details
git show v1.2.0

# Rename tag (if needed)
git tag v1.2.0_old v1.2.0
git tag -d v1.2.0
git push origin v1.2.0_old v1.2.0

# Delete tag locally and remotely
git tag -d v1.2.0
git push origin :refs/tags/v1.2.0

---

Tips:

• ✅ Always test locally before release
• ✅ Use semantic versioning consistently
• ✅ Document changes in CHANGELOG
• ✅ Wait for full workflow completion
• ✅ Test release artifacts before announcing

Remember: A good release is a tested release! 🚀