149 lines
5.7 KiB
Markdown
149 lines
5.7 KiB
Markdown
# 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. **Commit Messages**: Reference the relevant ADR (e.g., "feat(playout): add R2 sync per ADR-001").
|
|
5. **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 no prefix: `1.0.2`, `1.1.0`, `2.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` |
|
|
|
|
### Tag Triggers
|
|
|
|
| Tag Pattern | Workflow | What Happens |
|
|
| ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------ |
|
|
| `*.*.*` (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
|
|
|
|
# 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, update `CHANGELOG.md` if needed.
|
|
|
|
See the ADRs for architectural decisions and `docs/architecture/README.md` for the big picture. Thank you for contributing!
|