80 lines
3.8 KiB
Markdown
80 lines
3.8 KiB
Markdown
# Epoch Forge contributor guide
|
|
|
|
Epoch Forge is a CLI-first, local world-state manager. Its primary product
|
|
qualities are, in order: safety and reversibility, ease of use, compatibility
|
|
with existing repositories, and pleasant terminal output. Do not add a GUI,
|
|
web service, or TUI unless a task explicitly changes that scope.
|
|
|
|
## Product vocabulary
|
|
|
|
- A **repository** is a directory initialised by `efo init`.
|
|
- An **epoch** is an immutable-in-spirit snapshot of world state. Commands may
|
|
edit the checked-out epoch, but every destructive workflow must have a clear
|
|
recovery path.
|
|
- An **entity** is a typed game object such as a character, town, event,
|
|
blocker, calamity, or (eventually) organisation.
|
|
- An **identifier** may be a human-readable name or the stable `@UUID` form.
|
|
- The CLI is `efo`; `lib_efo` owns the domain and persistence logic while
|
|
`bin_efo` owns argument parsing and presentation.
|
|
|
|
## Engineering rules
|
|
|
|
1. Preserve persisted data compatibility. If a format change is unavoidable,
|
|
add a version/migration plan and fixtures before changing it.
|
|
2. Mutating commands must either complete fully or leave the prior on-disk
|
|
state usable. Prefer write-to-temporary-then-rename where practical.
|
|
3. Destructive commands require an explicit, documented recovery path. Model
|
|
vocabulary after Git where it helps: `status`, `log`, `diff`, `switch`,
|
|
`restore`, and later `stage`/`commit`.
|
|
4. Errors must say what failed, identify the relevant object/path, and suggest
|
|
the next useful command when one exists. Do not panic for user input or
|
|
repository corruption.
|
|
5. `efo --help` and every subcommand's `--help` are user documentation. Include
|
|
meaningful summaries, argument value hints, and examples where Clap allows.
|
|
6. Human output should be compact, aligned, Unicode-aware, and colour only when
|
|
appropriate for the terminal. Machine-readable output must remain plain and
|
|
stable. Never require a Nerd Font to understand essential output.
|
|
7. Keep domain operations in `lib_efo`; CLI handlers should parse, invoke, and
|
|
render. Avoid `unsafe`, unchecked `unwrap`, and hidden working-directory
|
|
mutations.
|
|
8. Custom organisation/entity fields are a planned compatibility direction.
|
|
Avoid closed designs that prevent adding schema-less metadata later.
|
|
|
|
## Quality gates
|
|
|
|
Run before each implementation commit:
|
|
|
|
```text
|
|
cargo fmt --all -- --check
|
|
cargo test --workspace --all-targets --all-features --locked
|
|
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
|
|
```
|
|
|
|
Add tests at the lowest useful layer and CLI integration tests for observable
|
|
workflows. Tests that touch a repository must use a temporary directory and
|
|
must not depend on execution order. Snapshot tests are appropriate for stable
|
|
human output; assertions on structured data are preferred for persistence.
|
|
|
|
Tarpaulin runs in CI with the tracked configuration and its documented line-
|
|
coverage floor. Do not restore `rust_autobadges`; Jenkins renders and publishes
|
|
the mutable badges from verified test and coverage results.
|
|
|
|
## Documentation and commits
|
|
|
|
- Keep the README short: purpose, honest capability summary, quick start,
|
|
safety model, and links into `docs/`.
|
|
- Keep commands, repository format, architecture, and roadmap in focused,
|
|
cross-linked files under `docs/`.
|
|
- Update documentation in the same commit as user-visible behavior.
|
|
- Maintain `AGENTS-TASKS.md`: mark completed items, add discoveries, and record
|
|
decisions that affect later work.
|
|
- Commit small coherent changes regularly. Use conventional subjects such as
|
|
`docs:`, `test:`, `fix:`, `feat:`, and `refactor:`. Never mix an unrelated
|
|
cleanup with a behavior change.
|
|
|
|
## Definition of done
|
|
|
|
A task is done when behavior is implemented, failure modes are covered, the
|
|
full quality gates pass, CLI help and relevant docs agree with reality, and the
|
|
change is committed with `AGENTS-TASKS.md` updated.
|