jellytau/docs/BUILD_RELEASE.md

# Build & Release Workflow

This document explains the automated build and release process for JellyTau.

## Overview

The CI/CD pipeline automatically:
1. ✅ Runs all tests (frontend + Rust)
2. ✅ Builds Linux binaries (AppImage + DEB)
3. ✅ Builds Android APK and AAB
4. ✅ Creates releases with artifacts
5. ✅ Tags releases with version numbers

## Workflow Triggers

### Automatic Trigger
When you push a version tag:
```bash
git tag v1.0.0
git push origin v1.0.0
```

The workflow automatically:
1. Runs tests
2. Builds both platforms
3. Creates a GitHub release with artifacts
4. Tags it as release/prerelease based on version

### Manual Trigger
In Gitea Actions UI:
1. Go to **Actions** tab
2. Click **Build & Release** workflow
3. Click **Run workflow**
4. Optionally specify a version
5. Workflow runs without creating a release

## Version Tagging

### Format
Version tags follow semantic versioning: `v{MAJOR}.{MINOR}.{PATCH}`

Examples:
- `v1.0.0` - Release version
- `v1.0.0-rc1` - Release candidate (marked as prerelease)
- `v1.0.0-beta` - Beta version (marked as prerelease)
- `v0.1.0-alpha` - Alpha version (marked as prerelease)

### Creating a Release

```bash
# Create and push a version tag
git tag v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

# Or create from main branch
git tag -a v1.0.0 -m "Release version 1.0.0" main
git push origin v1.0.0
```

### Release Status

Versions containing `rc`, `beta`, or `alpha` are marked as **prerelease**:
```bash
git tag v1.0.0-rc1      # ⚠️ Prerelease
git tag v1.0.0-beta     # ⚠️ Prerelease
git tag v1.0.0-alpha    # ⚠️ Prerelease
git tag v1.0.0          # ✅ Full release
```

## Workflow Steps

### 1. Test Phase
Runs on all tags and manual triggers:
- Frontend tests (`vitest`)
- Rust tests (`cargo test`)
- TypeScript type checking

**Failure:** Stops workflow, no build/release

### 2. Build Linux Phase
Runs after tests pass:
- Installs system dependencies
- Builds with Tauri
- Generates:
  - **AppImage** - Universal Linux binary
  - **DEB** - Debian/Ubuntu package

**Output:** `artifacts/linux/`

### 3. Build Android Phase
Runs in parallel with Linux build:
- Installs Android SDK/NDK
- Configures Rust for Android targets
- Builds with Tauri
- Generates:
  - **APK** - Android app package (installable)
  - **AAB** - Android App Bundle (for Play Store)

**Output:** `artifacts/android/`

### 4. Create Release Phase
Runs after both builds succeed (only on version tags):
- Prepares release notes
- Downloads build artifacts
- Creates GitHub/Gitea release
- Uploads all artifacts
- Tags as prerelease if applicable

## Artifacts

### Linux Artifacts

#### AppImage
- **File:** `jellytau_*.AppImage`
- **Size:** ~100-150 MB
- **Use:** Run directly on any Linux distro
- **Installation:**
  ```bash
  chmod +x jellytau_*.AppImage
  ./jellytau_*.AppImage
  ```

#### DEB Package
- **File:** `jellytau_*.deb`
- **Size:** ~80-120 MB
- **Use:** Install on Debian/Ubuntu/similar
- **Installation:**
  ```bash
  sudo dpkg -i jellytau_*.deb
  jellytau
  ```

### Android Artifacts

#### APK
- **File:** `jellytau-release.apk`
- **Size:** ~60-100 MB
- **Use:** Direct installation on Android devices
- **Installation:**
  ```bash
  adb install jellytau-release.apk
  # Or sideload via file manager
  ```

#### AAB (Android App Bundle)
- **File:** `jellytau-release.aab`
- **Size:** ~50-90 MB
- **Use:** Upload to Google Play Console
- **Note:** Cannot be installed directly; for Play Store distribution

## Release Notes

Release notes are automatically generated with:
- Version number
- Download links
- Installation instructions
- System requirements
- Known issues link
- Changelog reference

## Build Matrix

| Platform | OS | Architecture | Format |
|----------|----|----|--------|
| **Linux** | Any | x86_64 | AppImage, DEB |
| **Android** | 8.0+ | arm64, armv7, x86_64 | APK, AAB |

## Troubleshooting

### Build Fails During Test Phase
1. Check test output in Gitea Actions
2. Run tests locally: `bun run test` and `bun run test:rust`
3. Fix failing tests
4. Create new tag with fixed code

### Linux Build Fails
1. Check system dependencies installed
2. Verify Tauri configuration
3. Check cargo dependencies
4. Clear cache: Delete `.cargo` and `target/` directories

### Android Build Fails
1. Check Android SDK/NDK setup
2. Verify Java 17 is installed
3. Check Rust Android targets: `rustup target list`
4. Clear cache and rebuild

### Release Not Created
1. Tag must start with `v` (e.g., `v1.0.0`)
2. Tests must pass
3. Both builds must succeed
4. Check workflow logs for errors

## GitHub Release vs Gitea

The workflow uses GitHub Actions SDK but is designed for Gitea. For Gitea-native releases:

1. Workflow creates artifacts
2. Artifacts are available in Actions artifacts
3. Download and manually create Gitea release, or
4. Set up Gitea API integration to auto-publish

## Customization

### Change Release Notes Template

Edit `.gitea/workflows/build-release.yml`, section `Prepare release notes`:

```yaml
- name: Prepare release notes
  id: release_notes
  run: |
    # Add your custom release notes format here
    echo "Custom notes" > release_notes.md
```

### Add New Platforms

To add macOS or Windows builds:

1. Add new `build-{platform}` job
2. Set appropriate `runs-on` runner
3. Add platform-specific dependencies
4. Update artifact upload
5. Include in `needs: [build-linux, build-android, build-{platform}]`

### Change Build Targets

Modify Tauri configuration or add targets:

```yaml
- name: Build for Linux
  run: |
    # Add target specification
    bun run tauri build -- --target x86_64-unknown-linux-gnu
```

## Monitoring

### Check Status
1. Go to **Actions** tab in Gitea
2. View **Build & Release** workflow runs
3. Click specific run to see logs

### Notifications
Set up notifications for:
- Build failures
- Release creation
- Tag pushes

## Performance

### Build Times (Approximate)
- Test phase: 5-10 minutes
- Linux build: 10-15 minutes
- Android build: 15-20 minutes
- Total: 30-45 minutes

### Caching
Workflow caches:
- Rust dependencies (cargo)
- Bun node_modules
- Android SDK components

## Security

### Secrets
The workflow uses:
- `GITHUB_TOKEN` - Built-in, no setup needed
- No credentials needed for Gitea

### Verification
To verify build integrity:
1. Download artifacts
2. Verify signatures (if implemented)
3. Check file hashes
4. Test on target platform

## Best Practices

### Versioning
1. Follow semantic versioning: `v{MAJOR}.{MINOR}.{PATCH}`
2. Tag releases in git
3. Update CHANGELOG.md before tagging
4. Include release notes in tag message

### Testing Before Release
```bash
# Local testing before release
bun run test          # Frontend tests
bun run test:rust     # Rust tests
bun run check         # Type checking
bun run tauri build   # Local build test
```

### Documentation
1. Update [CHANGELOG.md](../CHANGELOG.md) with changes
2. Update [README.md](../README.md) with new features
3. Document breaking changes
4. Add migration guide if needed

## Example Release Workflow

```bash
# 1. Update version in relevant files (package.json, Cargo.toml, etc.)
vim package.json
vim src-tauri/tauri.conf.json

# 2. Update CHANGELOG
vim CHANGELOG.md

# 3. Commit changes
git add .
git commit -m "Bump version to v1.0.0"

# 4. Create annotated tag
git tag -a v1.0.0 -m "Release version 1.0.0

Features:
- Feature 1
- Feature 2

Fixes:
- Fix 1
- Fix 2"

# 5. Push tag to trigger workflow
git push origin v1.0.0

# 6. Monitor workflow in Gitea Actions
# Wait for tests → Linux build → Android build → Release

# 7. Download artifacts and test
# Visit release page and verify downloads
```

## References

- [Tauri Documentation](https://tauri.app/)
- [Semantic Versioning](https://semver.org/)
- [GitHub Release Best Practices](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases)
- [Android App Bundle](https://developer.android.com/guide/app-bundle)
- [AppImage Documentation](https://docs.appimage.org/)

---

**Last Updated:** 2026-02-13