Oxide/docs/development.md

Development Workflow

How work flows through the Oxide project: branches, testing gates, documentation, and how a stage progresses from start to sign-off.

Branch model

Oxide uses two long-lived branches:

Branch	Meaning
dev	Integration branch. Everything that builds and passes automated tests lands here first.
main	Stable branch. Only contains work that has been verified — automatically and, where relevant, manually approved.

The flow

1. Work lands on dev. Any change that can be fully verified by automated means (it builds, and its unit / integration / fuzz tests and benchmarks pass) is committed and pushed to dev as soon as it is complete and green.

2. Manual-test gate before main. If a change cannot be fully verified automatically — anything involving the GUI, rendering output, audio, input feel, or otherwise "you have to actually run the engine and look at it" — it stops at dev. The maintainer runs it, reviews the behavior, and reports back. Only after explicit approval is that version promoted to main.

3. Fully-automated changes can go straight to both. When a change is completely covered by automated tests (e.g. the math module — pure CPU logic with full unit/fuzz/benchmark coverage), it may be pushed to dev and main together, because the automated suite is the sign-off. No manual gate is needed.

Deciding which path a change takes

Ask: "Can a test prove this works without a human looking at it?"

• Yes → it can go to main as soon as tests pass (via dev).
• No (needs eyes/ears on a running engine) → push to dev, request manual testing, wait for approval, then promote to main.

When in doubt, treat it as needing manual testing and leave it on dev.

Promoting dev to main

git checkout main
git merge --ff-only dev    # or a regular merge if histories diverged
git push origin main
git checkout dev

Testing protocol

Every stage must pass all of the following before it is considered done (see also PLAN.md):

1. Unit tests — every module has tests for core behavior and edge cases, living in a #[cfg(test)] mod tests block beside the code.
2. Integration tests — the oxide-tests crate runs end-to-end and cross-module scenarios, including fuzz/property tests where appropriate.
3. Example review — each stage ships at least one runnable example in oxide-examples; both the maintainer and the implementer review it.
4. Benchmarks — performance-sensitive systems have criterion benchmarks; regressions against a stage's stated budget block sign-off.
5. Clippy + fmt — cargo clippy --all-targets -- -D warnings and cargo fmt --check must be clean. Engine/editor crates use #![deny(warnings)].

Quick local gate before any commit:

cargo fmt --check && \
cargo clippy --all-targets -- -D warnings && \
cargo test

Documentation policy

Documentation is written as the work is done, not after:

• Detailed docs live in docs/, one topic per file. The top-level README.md stays a short overview.
• A stage is not complete until its systems are documented in docs/ — usage (how to call it) and inner workings (how/why it works).
• When an API changes, update the affected doc and its code snippets in the same change, so docs never drift from the code.
• Keep the maintained project files current whenever structure, goals, or process change: CLAUDE.md, PLAN.md, README.md, .gitignore, and the relevant files in docs/.

Adding a new stage

1. Read PLAN.md for the stage's deliverables and test criteria.
2. Implement the system as one or more focused modules under engine/src/ (one concept per file, tests beside the code). Add editor support if the stage calls for it.
3. Add at least one example under examples/src/bin/.
4. Write the stage's documentation under docs/ and link it from docs/README.md.
5. Ensure the full testing protocol passes.
6. Update PLAN.md (mark the stage complete), README.md (status/features), and — if installed binaries or assets changed — install.sh.
7. Land on dev; promote to main per the branch model above.

Commit conventions

• Commit messages are written in the imperative mood and describe what and why.
• Group related changes; keep a commit focused on one logical change where practical.
• Co-authorship trailers are added when a commit is produced with AI assistance.