Contributing

Bug reports, feedback and patches are welcome. For anything larger than a small fix, open an issue first so the approach can be agreed before the work is done.

Setup

You need a Rust toolchain (1.88 or newer, via rustup), just, pre-commit and git. openscad is needed only for the real-library tests below, and mdbook only to preview the documentation site.

just setup    # rustfmt, clippy, and the pre-commit git hooks

Build, check, test

just fmt      # format
just check    # fmt-check + clippy with warnings as errors
just test     # unit and end-to-end tests
just run doctor   # run the CLI from source; arguments pass through

just check && just test must pass before a commit. The tests build throwaway git repositories under a temporary directory and use a temporary store, so they need git but no network and do not touch your own scadman store.

Two tests fetch real libraries from GitHub and render them with OpenSCAD. They are ignored by default:

cargo test -- --ignored

Layout

crates/scadman-core/   data model and logic: manifest, lockfile, resolver, store, environment, include-scan
crates/scadman-cli/    the `scadman` binary and its end-to-end tests
docs/                  user guides and design records; the source of the documentation site
fixtures/              real libraries pinned for tests, by reference

Logic belongs in scadman-core; the CLI stays a thin shell over it.

AGENTS.md holds the short form of the conventions and the design constraints. It is written for AI coding agents and applies equally to people. The reasoning behind the constraints is in the foundational decisions.

Documentation

The site at https://cameronbrooks11.github.io/scadman/ is built by mdBook from docs/, configured in book.toml. docs/SUMMARY.md is its table of contents: a new page is published only once it is listed there. Link between pages with relative .md links, and to anything outside docs/ with a full URL, so a link works both on the site and on GitHub.

just docs-serve   # preview at http://localhost:3000, rebuilding on change
just docs-build   # one-shot build into book/

A pull request that touches the docs builds the site in CI; merging to main publishes it.

Changes

Branch from main and open a pull request against it.
Conventional Commits: type(scope): subject, imperative and lowercase. One logical change per commit.
A behaviour change comes with a test. A bug fix comes with a test that fails without the fix.
Add a line under ## [Unreleased] in CHANGELOG.md for anything a user would notice.
Update the docs in the same change when behaviour they describe moves.
Never bypass the pre-commit hooks.

CI runs on every pull request: formatting, a type-check, a check that Cargo.lock matches Cargo.toml, the test suite, and a type-check on the minimum supported Rust version. Clippy also runs, as an advisory job that does not block.

Releasing

Set the new version in the root Cargo.toml and refresh Cargo.lock (cargo check).
Rename ## [Unreleased] in CHANGELOG.md to the version and date, add a fresh empty ## [Unreleased] above it, and add the link at the bottom of the file.
Update the version in the cargo install line, in both README.md and docs/getting-started.md.
Merge, then tag the merge commit v<version> and push the tag.

The tag triggers the release workflow, which builds the Linux binary from the committed Cargo.lock, writes checksums.txt, and publishes a GitHub release whose notes are that version’s CHANGELOG section. It fails if the section is missing.

Keyboard shortcuts