Contributing

Game files

You need your own copy of Blur. Never commit game files or anything generated from them: the ISO, game binaries, P-code, generated recomp code, the app icon. CI and the build take them from the user’s disc or a private store. The only exceptions are the fan-wiki icons and car names in examples/live-timing.

Getting started

Build from source, then see Testing and Dev tooling. Fixes must be verified on the recompiled engine; the Unicorn emulator is being removed.

Branches and releases

Gitflow with semver:

• develop is the integration branch; day-to-day work lands there.
• feature/<name> branches from develop and merges back with --no-ff. Use one git worktree per parallel feature.
• release/X.Y.Z branches from develop (version bump, fixes only) and merges to main, tagged vX.Y.Z, and back to develop.
• hotfix/X.Y.Z branches from main and merges to main (tagged) and develop.
• main is released code only. The version comes from the tag at build time.

See CI and releases.

Design decisions

Past design decisions are recorded in docs/decisions/ in the repository. Read the relevant ones before changing architecture, tooling or workflow, and add a new record rather than rewriting an old one.

Comments

Write no comments by default. Add one only for a non-obvious why: a hidden constraint, a workaround for a specific bug, behaviour imposed by an external platform. Don’t narrate what the code does, don’t reference the task or issue that produced the change, and don’t leave commented-out code. Keep the glossary terms in GLOSSARY.md when naming things.

Docs

Pages live in docs/ and each needs title: frontmatter instead of a leading heading. README.md stays a one-screen summary. This file is published on the site from the single copy at the repo root.

Issues

Work is tracked in Forgejo Issues. Milestones are epics. Triage labels: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix.