euchre_camp/.gitea/WORKFLOW_ARCHITECTURE.md

# Gitea Actions Workflow Architecture

This document describes the workflow architecture for version bumping, testing, and releases.

## Overview

The workflow architecture uses a three-step process:
1. **PR Workflow**: Runs tests on PRs and analyzes commits for bump type
2. **Test Workflow**: Runs unit tests on all branch pushes (except version bumps)
3. **Release Workflow**: Bumps version, creates tags, builds Docker images, and deploys on main branch pushes

## Workflow Files

### 1. `.gitea/workflows/pr.yml` (Pull Request Workflow)

**Trigger**: Pull requests to `main` branch

**Purpose**:
- Run unit tests on every PR (fast feedback)
- Run acceptance tests with SQLite database
- Analyze commits to determine bump type (major/minor/patch)
- Comment the suggested bump type on the PR

**Test Execution**:
- **Unit Tests**: Run first, fast execution
- **Acceptance Tests**: Run after unit tests pass, uses SQLite database
- **Database**: SQLite with `DATABASE_URL=file:./prisma/ci.db`
- **Secrets**: Uses `BETTER_AUTH_SECRET` for authentication

**Bump Type Detection**:
- **Major**: Breaking changes detected (`BREAKING CHANGE` or `!:` in commit messages)
- **Minor**: Feature commits detected (`feat:` prefix)
- **Patch**: Default for fixes and other changes

### 2. `.gitea/workflows/test.yml` (Test Workflow)

**Trigger**: Pushes to any branch (including main)

**Purpose**:
- Run unit tests on all branch pushes
- Skip auto-generated version bump commits (handled by release workflow)

**Key Features**:
- Runs on all branches including main
- Skips commits with "chore: bump version" message
- Fast execution for quick feedback

### 3. `.gitea/workflows/release.yml` (Release Workflow)

**Trigger**: Pushes to `main` branch (after PR merge)

**Purpose**:
- Determine bump type from merge commit or PR commits
- Bump version in `package.json` and `CHANGELOG.md`
- Commit the version bump
- Create git tag for the release
- Run tests inside Docker container (with PostgreSQL)
- Build production Docker image
- Push images to registry
- Deploy to dev environment

**Key Features**:
- Skips commits that are auto-generated version bumps
- Uses `DOCKER_LOGIN` and `DOCKER_PASSWORD` secrets for registry auth
- Handles existing git tags gracefully
- Runs comprehensive tests in production-like environment

## Version Bump Logic

### Step 1: PR Analysis (pr.yml)
When a PR is opened or updated:
1. Fetch the merge base with `main`
2. Analyze all commits in the PR
3. Determine bump type based on commit messages:
   - Breaking changes → major
   - Features → minor
   - Fixes → patch
4. Comment the suggested bump type on the PR

### Step 2: Release (release.yml)
When a PR is merged to `main`:
1. Check if the commit is an auto-bump (skip if so)
2. Analyze the merge commit message or PR commits
3. Run `node scripts/bump-version.js <type> --yes`
4. Commit the version bump changes
5. Create and push git tag
6. Build and push Docker images

## Environment Variables & Secrets

### Required Secrets
- `DOCKER_LOGIN`: Username for Docker registry authentication
- `DOCKER_PASSWORD`: Password for Docker registry authentication
- `GITEA_TOKEN` (optional): For pushing back to repo (if needed)

### Environment Variables
- `REGISTRY`: Docker registry URL (default: `docker.notsosm.art`)
- `IMAGE_NAME`: Docker image name (default: `euchre-camp`)

## Example Workflow

### Scenario: Feature PR
1. Developer opens PR with commits:
   - "feat: add new feature"
   - "fix: resolve edge case"
2. PR workflow runs:
   - Unit tests pass
   - Bump type analysis suggests "minor"
   - Comment posted on PR: "Suggested bump: MINOR"
3. Developer merges PR
4. Release workflow runs:
   - Detects minor bump from commits
   - Bumps version from 0.1.1 → 0.2.0
   - Commits version bump
   - Creates tag v0.2.0
   - Builds and pushes Docker image
   - Deploys to dev

### Scenario: Breaking Change PR
1. Developer opens PR with commit:
   - "feat!: breaking API change"
2. PR workflow runs:
   - Detects breaking change marker
   - Suggests "major" bump
   - Comments on PR
3. Developer merges PR
4. Release workflow runs:
   - Detects major bump
   - Bumps version from 0.1.1 → 1.0.0
   - Creates tag v1.0.0
   - Proceeds with build and deploy

## Database Configuration for CI

### SQLite for CI Acceptance Tests
- **Why SQLite**: No database server required, perfect for CI environments
- **Usage**: PR workflow runs acceptance tests with SQLite database
- **Configuration**: `DATABASE_PROVIDER=sqlite`, `DATABASE_URL=file:./prisma/ci.db`
- **Benefits**: Fast, isolated, no external dependencies

### PostgreSQL for Production
- **Usage**: Release workflow runs tests in Docker with PostgreSQL
- **Configuration**: Uses dummy PostgreSQL URL for Docker builds
- **Benefits**: Production-like environment, catches PostgreSQL-specific issues

### Database Provider Detection
The application automatically detects the database provider:
- `DATABASE_PROVIDER` environment variable (defaults to `sqlite`)
- `prisma.ts` conditionally uses PrismaPg adapter for PostgreSQL
- Better Auth configured with appropriate provider

## Benefits

1. **No CI Loops**: Version bump commits are detected and skipped
2. **Clear Communication**: PR comments inform developers of impact
3. **Semantic Versioning**: Automated adherence to semver rules
4. **Traceability**: Git tags and changelog reflect all changes
5. **Safe Releases**: Tests run before version bump and deployment
6. **Fast CI**: SQLite tests run quickly without database server setup
7. **Comprehensive Testing**: Both unit and acceptance tests in PR workflow

## Future Enhancements

- Add GitHub/Gitea Release creation
- Slack/Discord notifications on release
- Automatic rollback on test failure
- Multi-environment deployment (dev/staging/prod)