# 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:

    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

    # 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:

    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:

      chmod +x JellyTau_*.AppImage
      ./JellyTau_*.AppImage

#### DEB Package

- File: `JellyTau_*.deb`
- Size: ~80-120 MB
- Use: Install on Debian/Ubuntu/similar
- Installation:

      sudo dpkg -i JellyTau_*.deb
      jellytau

- Note: the Debian package is named `jelly-tau` (Tauri kebab-cases `productName`), while the command stays `jellytau`. The package declares `Replaces`/`Conflicts`/`Provides: jellytau`, so upgrading from a release built before the rename replaces it rather than installing a second copy.

#### RPM Package

- File: `JellyTau-*.rpm`
- Use: Install on Fedora/openSUSE/similar
- Installation:

      sudo rpm -i JellyTau-*.rpm
      jellytau

### Android Artifacts

#### APK

- File: `jellytau-release.apk`
- Size: ~60-100 MB
- Use: Direct installation on Android devices
- Installation:

      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`:

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

    - 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

    # 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 with changes
2. Update README.md with new features
3. Document breaking changes
4. Add migration guide if needed

## Example Release Workflow

    # 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
- Semantic Versioning
- GitHub Release Best Practices
- Android App Bundle
- AppImage Documentation

Last Updated: 2026-02-13