OpenCoD2-Plus
Call of Duty 2 client & server, rebuilt
Loading...
Searching...
No Matches
Development guide

Rules for contributors and AI agents. Tooling details: ../development/.

Workflow

Step Rule
Branch one branch per piece of work, from dev (the development branch; main is the stable one)
Investigate reproduce first; find the root cause; compare with the 1.3 binary (validation)
Change smallest change that matches the original; vendored code upstream first (vendored)
Verify scripts/build_check.py all, unit tests, scripts/check_docs.py, the runtime tests the change touches; the full suite before merging (testing)
Review a fresh reviewer reads the whole branch before merge
Merge git merge --ff-only into dev; dev goes into main when its changes are stable
Publish never push without the maintainer's decision

Commits

  • English; the subject says what is now right: area: what changed, as the 1.3 binary.
  • Areas used: client, cgame, gfx, fx, server, build, scripts, test, docs.
  • Body: the cause, what the original does (with its address), what it fixed.
  • One concern per commit; docs that the change makes wrong are updated in the same commit.

Doc-sync rules

When you… Update
commit anything first review all the docs and docs/roadmap/debt.md against the change; fix what it makes stale, remove the debt it closes, add the debt it leaves
change a boundary, add a bridge module or an exception docs/architecture/boundaries.md (+ an ADR if it is a decision)
add or change a build option, variant or check docs/development/building.md, SYSTEM_SUMMARY.md
add or change a test script docs/development/testing.md
fix or leave open a known problem docs/roadmap/debt.md
change a subsystem's state SYSTEM_SUMMARY.md, the subsystem note in docs/architecture/
finish a piece of work (merge) a new stage at the top of PROJECT_MEMORY.md
take a lasting architectural decision a new ADR (docs/architecture/adr/)

python3 scripts/check_docs.py must report nothing.

Recipes

Task Steps
Fix an engine bug reproduce → locate the original function → compare → fix with the address in a comment → test → note in the subsystem doc if it explains how something works
Add an engine ↔ OpenCoD2-Plus Server crossing add it to the interface list in test/ → regenerate with scripts/gen_script_bridge.py → add its line to test/<module>_abi.txt and _abi_x64.txt from the engine's declaration (format in scripts/engine_abi.py; the generator refuses a crossing without one) → build_check.py
Add a test script scripts/<name>_test.py with a usage docstring, exit 0 on pass, skipped without a CD key if it needs a real client → add to docs/development/testing.md
Add an ADR copy the template in docs/architecture/adr/README.md, next number, add to the index

Memory entry

## YYYY-MM-DD — topic
- What changed and why it mattered (one line).
- What was rejected or deferred, and why.
- What is left open (link debt.md).

Never

  • Commit a CD key, a personal path or a private server address.
  • Edit vendored files, or accepted ADRs (beyond marking one superseded).
  • Claim a fix works without running the test that shows it.