3.8 KiB
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
@UUIDform. - The CLI is
efo;lib_efoowns the domain and persistence logic whilebin_efoowns argument parsing and presentation.
Engineering rules
- Preserve persisted data compatibility. If a format change is unavoidable, add a version/migration plan and fixtures before changing it.
- Mutating commands must either complete fully or leave the prior on-disk state usable. Prefer write-to-temporary-then-rename where practical.
- Destructive commands require an explicit, documented recovery path. Model
vocabulary after Git where it helps:
status,log,diff,switch,restore, and laterstage/commit. - 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.
efo --helpand every subcommand's--helpare user documentation. Include meaningful summaries, argument value hints, and examples where Clap allows.- 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.
- Keep domain operations in
lib_efo; CLI handlers should parse, invoke, and render. Avoidunsafe, uncheckedunwrap, and hidden working-directory mutations. - 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:
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 and rust_autobadges are release-time tools. Do not run them in CI or
for routine commits. Refresh their badges only for a significant release.
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:, andrefactor:. 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.