# 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! 🚀