# Contributing to Linear Void

Thank you for considering contributing to Linear Void!

## Development Process

1. **Read the Architecture First**: All design decisions are documented in `docs/architecture/README.md` (arc42 template) and the ADRs in `docs/architecture/adr/` (ADR-001 to ADR-007).
2. **Follow the Structure**: Use the folder layout defined in ADR-002 (`frontend/`, `backend/playout/`, `backend/chat/`, `infrastructure/`, etc.).
3. **Update Documentation Before Code**: Create or update an ADR before implementing significant changes.
4. **Update TODO.md**: Plan tasks in `.github/instructions/TODO.md`, mark as completed, and move finished sections to `DONE.md`.
5. **Commit Messages**: Reference the relevant ADR (e.g., "feat(playout): add R2 sync per ADR-001").
6. **Test with Docker**: Run `docker compose up --build` to test changes.

## Repository

- **Primary**: [git.allucanget.biz/zwitschi/linearvoid](https://git.allucanget.biz/zwitschi/linearvoid)
- **Container Registry**: `git.allucanget.biz/zwitschi/linearvoid/<service>:latest`
- **CI/CD**: Gitea Actions with self-hosted runners (see `.gitea/workflows/`)

## Code Style

- Go: Use standard formatting (`go fmt`).
- TypeScript: `tsc --noEmit` for type-checking (see `frontend/package.json`).
- CSS: Design-token system via CSS custom properties in `frontend/src/style.css`. No utility framework.

## Pull Requests

- Open PRs on [Gitea](https://git.allucanget.biz/zwitschi/linearvoid).
- Reference the related ADR in the PR description.
- Ensure all tests pass and documentation is updated.
- The CI workflow will validate normalization, linting, and Docker builds.

## Versioning and Releases

### Version Scheme

Linear Void follows **Semantic Versioning** ([SemVer](https://semver.org)): `MAJOR.MINOR.PATCH`.

- **MAJOR** — breaking changes to the viewer, API, or deployment model.
- **MINOR** — new features (endpoints, admin tabs, UI capabilities) that are backward-compatible.
- **PATCH** — bug fixes, optimizations, documentation polish.

Git tags use a `v` prefix: `1.0.2`, `1.1.0`, `v2.0.0`.

### Where Versions Are Declared

| File                           | Token          | Example                   |
| ------------------------------ | -------------- | ------------------------- |
| `frontend/package.json`        | `"version"`    | `"1.0.2"`                 |
| `CHANGELOG.md`                 | `## [X.Y.Z]`   | `## [1.0.2] - 2026-08-05` |
| `README.md`                    | Version badge  | `version-1.0.2-blue`      |
| `.github/instructions/TODO.md` | Section header | `## Version 1.0.2`        |

### Tag Triggers

| Tag Pattern         | Workflow            | What Happens                                                                                                       |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `v*` (e.g. `1.0.2`) | `release.yml`       | Builds all 3 images, pushes to registry with semver tags (`1.0.2`, `1.0`, `latest`), creates Gitea Release via API |
| Push to `main`      | `ci.yml` → `cd.yml` | CI builds + pushes images with `main`/`latest` tags, CD deploys to production                                      |

### Full Release Procedure

#### Step 1: Bump version numbers

Update these files to the new version (replace `X.Y.Z`):

- [frontend/package.json](frontend/package.json)
- [CHANGELOG.md](CHANGELOG.md) — add new section at top
- [README.md](README.md) — version badge

```bash
# frontend/package.json
"version": "X.Y.Z"

# CHANGELOG.md — add new section at top
## [X.Y.Z] - YYYY-MM-DD

# README.md — version badge
version-X.Y.Z-blue
```

#### Step 2: Write changelog

Add entries under `## [X.Y.Z]` in `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com) format (`Added`, `Changed`, `Fixed`, `Removed`).

#### Step 3: Commit and tag

```bash
# Stage all version bumps + changelog
git add frontend/package.json CHANGELOG.md README.md .github/instructions/TODO.md

# Commit
git commit -m "chore: bump version to X.Y.Z"

# Create annotated tag
git tag -a X.Y.Z -m "Release X.Y.Z"

# Push commit and tag
git push origin main
git push origin X.Y.Z
```

#### Step 4: Verify CI/CD

- CI workflow (`ci.yml`) runs on push to `main` → builds & pushes `main`/`latest` images.
- Release workflow (`release.yml`) triggers on `X.Y.Z` tag → builds images with semver tags (`X.Y.Z`, `X.Y`, `latest`), creates Gitea Release.
- CD workflow (`cd.yml`) triggers after CI completes → deploys to production.

Monitor at: [git.allucanget.biz/zwitschi/linearvoid/actions](https://git.allucanget.biz/zwitschi/linearvoid/actions)

#### Step 5: Verify release

Check the Gitea Releases page for the new tag:
[git.allucanget.biz/zwitschi/linearvoid/releases](https://git.allucanget.biz/zwitschi/linearvoid/releases)

### Manual Release (workflow_dispatch)

If a tag push fails or a re-release is needed:

1. Go to [Actions → Release workflow](https://git.allucanget.biz/zwitschi/linearvoid/actions?workflow=release.yml)
2. Click "Run workflow"
3. Enter version (e.g. `1.0.2`)
4. The workflow builds images, pushes semver tags, and creates the Gitea Release

### Docker Image Tags

Every release produces these tags in the Gitea Container Registry:

| Image     | Tags                     |
| --------- | ------------------------ |
| `playout` | `X.Y.Z`, `X.Y`, `latest` |
| `chat`    | `X.Y.Z`, `X.Y`, `latest` |
| `nginx`   | `X.Y.Z`, `X.Y`, `latest` |

Example for `1.0.2`:

```text
git.allucanget.biz/zwitschi/linearvoid/chat:1.0.2
git.allucanget.biz/zwitschi/linearvoid/chat:1.0
git.allucanget.biz/zwitschi/linearvoid/chat:latest
git.allucanget.biz/zwitschi/linearvoid/playout:1.0.2
git.allucanget.biz/zwitschi/linearvoid/playout:1.0
git.allucanget.biz/zwitschi/linearvoid/playout:latest
```

### Moving Completed Tasks

After release, move completed sections from `TODO.md` to `DONE.md` and update `CHANGELOG.md` if needed. The `DONE.md` file serves as the historical record linking tasks to releases.

See the ADRs for architectural decisions and `docs/architecture/README.md` for the big picture. Thank you for contributing!