Contributing

​

PR workflow

​

Branch naming

​

Step-by-step

1. Fork the repository on GitHub and clone your fork locally.
2. Create a branch from main:
   git checkout main && git pull origin main
   git checkout -b feat/my-feature
   
3. Make your changes. Run tests and linting before committing:
   just test          # run root pytest suite
   just lint          # run all pre-commit hooks
   
4. Commit using Conventional Commits format.
5. Push your branch and open a pull request against main.
6. Address review feedback. Push additional commits — the PR will be squash-merged.

​

Code review expectations

• Every PR requires at least one approving review before merge.
• Reviewers check for correctness, test coverage, style compliance, and documentation updates.
• Keep PRs focused. If a change touches multiple services, consider splitting into separate PRs.
• CI must pass (lint, unit tests, type checks) before merge is allowed.
• PRs are squash-merged into main to keep a linear history.

​

Commit style

​

Format

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

​

Types

​

Scopes

​

Examples

# Feature with scope
feat(bridge): add XMPP MUC room join/part relay

# Bug fix
fix(irc): correct cloak key fallback in prepare-config.sh

# Documentation
docs(ops): add SSL certificate renewal runbook

# Breaking change (major version bump)
feat(bridge)!: switch event bus from polling to WebSocket

BREAKING CHANGE: bridge config.yaml now requires a `ws_url` field.

# Chore with body
chore(deps): bump UnrealIRCd image to 6.1.8

Updated base image tag in infra/compose/irc.yaml.
Tested locally with `just dev` — all services start cleanly.

​

Interactive commits

pnpm exec cz

​

Pre-commit hooks

​

Setup

1. Install pre-commit (included in the Python dev dependencies):
   uv sync          # installs pre-commit into the venv
   
2. If your environment sets core.hooksPath (some editors and CI systems do this), unset it first — otherwise pre-commit install will silently fail to register hooks:
   git config --unset-all core.hooksPath
   
3. Install the git hooks:
   uv run pre-commit install
   uv run pre-commit install --hook-type commit-msg   # enables commitlint
   
4. Verify hooks are active:
   uv run pre-commit run --all-files
   
   This is equivalent to just lint.

​

Hook reference

​

Running hooks manually

# Run all hooks on all files
just lint

# Run a specific hook
uv run pre-commit run ruff-check --all-files
uv run pre-commit run shellcheck --all-files

# Run hooks only on staged files (default git hook behaviour)
uv run pre-commit run

​

Code style

​

Python — ruff

# Lint with auto-fix
uv run ruff check --fix .

# Format
uv run ruff format .

# Check without modifying files
uv run ruff check .
uv run ruff format --check .

​

TypeScript / JSX — Biome (ultracite)

# Check for issues
cd apps/web && pnpm run check

# Auto-fix
cd apps/web && pnpm run fix

# Or via the pre-commit hook (runs automatically on apps/web/ JS/TSX files)
uv run pre-commit run lint-web --all-files

Note: The ultracite check command currently has a known issue where it expects a .gitignore in apps/web/. This does not affect builds (pnpm run build works fine).

​

Lua — luacheck

# Run via pre-commit
uv run pre-commit run luacheck --all-files

# Run directly with Docker (same as the hook)
docker run --rm -v "$PWD":/data ghcr.io/lunarmodules/luacheck:latest .

​

Shell — shellcheck and shfmt

# Run shellcheck
uv run pre-commit run shellcheck --all-files

# Run shfmt
uv run pre-commit run shfmt --all-files

# Run shellcheck directly
shellcheck scripts/*.sh

​

Related pages

• Testing — test directory layout, running tests, fixtures
• Adding a Service — checklist for adding a new service to the monorepo
• Security — secret management and Gitleaks configuration