# 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:
  ```bash
  # 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:
  ```bash
  git add .
  git commit -m "Bump version to v1.2.0"
  git push origin master
  ```

## Final Check Before Release

- [ ] Run full test suite:
  ```bash
  bun run test          # Frontend tests
  bun run test:rust     # Rust tests
  bun run check         # Type checking
  ```

- [ ] Build locally (optional but recommended):
  ```bash
  # Test Linux build
  bun run tauri build

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

- [ ] No uncommitted changes:
  ```bash
  git status  # Should show clean working directory
  ```

## Release (Tag & Push)

```bash
# 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-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)

- [ ] 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:

```bash
# 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](../../CHANGELOG.md)
- [Issues](../../issues)
- [Discussion](../../discussions)

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

## Quick Commands

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