# Gitea Actions Workflow Architecture

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

## Overview

The workflow architecture uses a two-step process:
1. **PR Workflow**: Analyzes commits and suggests bump type
2. **Release Workflow**: Bumps version, creates tags, and builds Docker images on merge

## Workflow Files

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

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

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

**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/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
- 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

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

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

## Future Enhancements

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