full-count / Docs / Development

Development

full-count is a small Rust application — a handful of modules, one binary, no workspace members. If you're comfortable with cargo you already know how to build it.

Building

cargo build                               # debug
cargo build --release                     # optimized
cargo build --release --features advanced-stats

Running tests

cargo test                                # standard suite
cargo test --features advanced-stats      # feature-gated paths too

CI (GitHub Actions) runs both test lines on every push and pull request, plus cargo fmt --check and cargo clippy -- -D warnings.

Lint & format

cargo fmt                                 # apply rustfmt
cargo clippy -- -D warnings              # treat warnings as errors
cargo clippy --features advanced-stats -- -D warnings

Module layout

File	Responsibility
`src/main.rs`	Entry point, CLI parsing, terminal setup, event loop.
`src/app.rs`	Top-level `App` state: screens, input modes, setup data, undo stack.
`src/game.rs`	The `GameState` domain model: innings, runners, stats, substitutions, and the rules.
`src/input.rs`	Per-screen key handlers; the state machine that turns keystrokes into `app`/`game` mutations.
`src/ui.rs`	ratatui rendering for every screen.
`src/persist.rs`	JSON save/load and the `~/.full-count/saves/` directory logic.
`src/export.rs`	Askama-driven HTML scorecard export.
`templates/scorecard.html`	The Askama template used by `export.rs`.

Contributing

Keep changes small and test-covered; the project favors a growing test suite over speculative abstractions.
Every user-facing change needs a matching docs update — see Keeping the docs in sync.
Clippy must be clean (-D warnings). Formatting is enforced via cargo fmt --check.
Prefer adding a unit test under #[cfg(test)] in the same module over building a separate integration file, unless the test genuinely spans modules.

Keeping the docs in sync

Docs are first-class. When you change the user-facing behavior of the app, the documentation site in docs/ has to move with it. The rules:

New keybinding? Update Scoring reference, the landing-page keygrid in docs/index.html, and the setup/gameplay sections of Getting started if relevant.
New CLI flag? Update Getting started and Saves & exports.
New save-file field, directory, or sanitization rule? Update Saves & exports.
New advanced-stats metric? Update Advanced stats.
New replay behavior? Update Replay mode.
Any user-facing change worth noting? Add an entry to the Changelog below.

Automation backing these rules lives in AGENTS.md and .github/copilot-instructions.md so every AI-assisted change is nudged into updating the site. Please keep those files honest.

Changelog & releases

Release notes live in CHANGELOG.md on GitHub. Prebuilt binaries for Linux, macOS, and Windows are attached to each entry on the Releases page.

Both are generated automatically by release-plz from Conventional Commit messages on master — there is nothing to hand-edit on this page.

How releases happen

Land commits on master with conventional subjects (feat:, fix:, feat!:, etc.).
release-plz opens or updates a chore: release pull request with the next version, a refreshed Cargo.lock, and the new CHANGELOG.md entry.
Merging that PR tags the release and creates the GitHub Release.
The tag triggers the release workflow, which builds the three OS binaries and attaches them to the release.