# 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`

```sh
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`](../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:

```sh
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/`](README.md), 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`](../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`](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.