linearvoid/CONTRIBUTING.md

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
• 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.
• 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): 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
• CHANGELOG.md — add new section at top
• README.md — version badge

# 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 format (Added, Changed, Fixed, Removed).

Step 3: Commit and tag

# 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

Step 5: Verify release

Check the Gitea Releases page for the new tag: 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
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:

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!