Homer Simpson
9eead719b0
Full project snapshot migrated to new Gitea remote without history: engine, editor, physics, script, examples, tests, docs, and assets. Relicensed from GPLv3 to MIT and updated repo URLs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
112 lines
4.5 KiB
Markdown
112 lines
4.5 KiB
Markdown
# 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.
|