Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

CONTRIBUTING.md for outside contributors; README status and a Contributing section

bherbruck2ea99556212e
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000000..f7f0c9b0d3
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,153 @@
+# Contributing to SolveCraft
+
+SolveCraft is an open-source parametric 3D CAD app written in pure Rust, in the style of
+Autodesk Fusion. You sketch on a plane, constrain the sketch, turn profiles into solids, and
+change a parameter to watch the timeline rebuild. It runs as a desktop app (Windows, Linux), in
+the browser (wasm + WebGPU/WebGL2), headless from a CLI, and as an MCP server that AI agents can
+model with.
+
+Help is welcome, whether that's a one-line fix or owning a whole area. This page covers how to
+build it, how the code is laid out, the few rules that aren't negotiable, and where help is
+needed most.
+
+## Get it running (about 10 minutes on a fast machine)
+
+You need stable Rust 1.90 or newer. For the web
+build you also need `rustup target add wasm32-unknown-unknown` and [`trunk`](https://trunkrs.dev).
+
+```sh
+git clone https://github.com/bherbruck/solvecraft && cd solvecraft
+cargo run --release -p solvecraft -- --sample # desktop app with a sample part
+cargo test --workspace --release # unit, engine and UI-scenario tests
+cargo xtask ci # everything a PR must pass (see below)
+```
+
+Web: `cd apps/solvecraft-web && trunk serve --release`, then open the printed URL (`?sample`
+opens the sample part, `?webgl` forces WebGL2). Saving and opening files in the browser needs
+HTTPS or localhost, because it uses the Origin Private File System.
+
+Windows from Linux: `cargo xwin build --release --target x86_64-pc-windows-msvc -p solvecraft`.
+
+## How the code is laid out
+
+The [README](README.md#architecture) has the layer table. The short version:
+
+- `crates/geom`: vectors, planes, meshes, measures.
+- `crates/sketch`: our own constraint solver, plus profile finding.
+- `crates/kernel`: the B-rep kernel boundary. It wraps [truck](https://github.com/ricosjp/truck),
+ and it's the only crate allowed to touch truck. Fillets, chamfers, shell/offset, Delete Face,
+ Split Face, STEP/IGES read and write, and face provenance are our own code here. Patched
+ copies of three truck crates live in `vendor/` and are excluded from our fmt/clippy rules.
+- `crates/doc`: the document. It holds parameters and expressions, the feature timeline and its
+ incremental rebuild, components and occurrences, joints, appearances, and persistent naming.
+- `crates/io`: design files and mesh formats (3MF, STL, OBJ).
+- `crates/engine`: the session and the command registry. **Everything the user can do is a
+ command**, and the toolbar, dialogs, scripts, CLI, control channel and MCP all run the same
+ commands.
+- `crates/ui-egui`: the desktop/web front end (egui + wgpu). It's swappable; nothing below it
+ depends on egui.
+- `crates/mcp`, `apps/solvecraft`, `apps/solvecraft-cli`, `apps/solvecraft-web`.
+
+`cargo xtask layers` fails the build if a lower layer depends on a higher one.
+
+## Rules that aren't negotiable
+
+1. **Clean-room.** We observe Fusion as a black box: its UI, how parts it builds measure, and
+ what it does with a given input. We never copy Autodesk code, icons, artwork, help text,
+ tooltips, templates or materials, and we never commit files Fusion produced. Command ids are
+ our own (`solid.fillet`, not Fusion's internal names).
+2. **No GPL/LGPL/AGPL code, not even reading it.** That rules out OpenCASCADE, FreeCAD
+ (including planegcs), SolveSpace, CadQuery/OCP, LibreCAD and QCAD. SolveCraft is
+ MIT OR Apache-2.0, and its solver and blends are written from the maths. Permissive
+ dependencies are fine. Note which one you're adding and why in the PR.
+3. **Every asset is original or openly licensed and has a row in
+ [ATTRIBUTION.md](ATTRIBUTION.md).** Icons are drawn in code (`crates/ui-egui/src/icons.rs`).
+ `cargo xtask assets` enforces this.
+4. **Never crash.** People trust a CAD app with their work.
+ - Non-test code never uses `unwrap`, `expect`, `panic!` or indexing on input-derived data.
+ There's no `unsafe`, and clippy denies it.
+ - An unsupported case returns an error ("not supported yet: …"); it never panics.
+ - Every call into truck goes through `solvecraft_kernel::guard`.
+ - Every crash fix comes with a regression test.
+5. **Everything is a command, with a test.** A new feature means a `CommandSpec` in
+ `crates/engine/src/cmd/`, engine tests that measure the result (volume, area,
+ face/edge/vertex counts against a value you can derive), and for UI work a scenario (below).
+
+[AGENTS.md](AGENTS.md) has the long form of these rules. It's written for AI agents, but it's
+the most complete description of the house style.
+
+## Tests
+
+| What | Where | Run |
+|---|---|---|
+| Unit and engine tests | next to the code, or `*_tests.rs` files | `cargo test --workspace --release` |
+| UI scenarios | `crates/ui-egui/tests/scenarios/*.json` | part of `cargo test` |
+| Fusion oracle | `cargo xtask oracle` | needs the local oracle data (see below) |
+
+**UI scenarios** drive the real app headless: start a tool, click a plane or a sketch point,
+press keys, then assert on the result.
+
+```json
+[
+ {"start": "sketch.create"},
+ {"click": {"plane": "XY"}},
+ {"start": "sketch.rectangle.two_point"},
+ {"click": {"sketch": [0, 0]}},
+ {"click": {"sketch": [40, 30]}},
+ {"expect": {"errors": 0}}
+]
+```
+
+A new `.json` file in that folder is picked up automatically. To record a bug before it's fixed,
+put `{"pending": "why"}` in the scenario, and remove it in the PR that fixes the bug.
+
+**Release mode matters.** CI runs the tests with `--release`. truck has debug-only assertions
+that can fail on valid geometry, so if a test fails only in debug, say so in the PR.
+
+**The Fusion oracle** is a set of 76 reference parts, each built in Fusion from a recipe.
+SolveCraft rebuilds the same recipe and compares volume, area and topology counts with Fusion's
+measurements; [docs/oracle.md](docs/oracle.md) has the current results. The recipes and
+measurements live outside the repo (`plan/`, gitignored), because they come from a Fusion
+install. If you work on geometry and want to check against it, ask in an issue.
+
+## Sending a change
+
+1. Work is tracked in [GitHub issues](https://github.com/bherbruck/solvecraft/issues), labelled
+ by area (`area:kernel`, `area:sketch`, `area:doc`, `area:ui`, `area:infra`). Before starting,
+ comment on the issue so it gets the `in progress` label and two people don't build the same
+ thing. For anything bigger than a bug fix that has no issue yet, open one first.
+2. Branch from `main` and keep the PR to one topic.
+3. Run `cargo xtask ci` before pushing. It runs fmt, clippy (`-D warnings`), the tests in
+ release mode, the asset and layer checks, and the wasm build check. A PR has to pass it.
+4. Reference the issue (`Fixes #12`). In the PR, say what you tested and how. For geometry work, include the measured numbers (and
+ the expected ones).
+
+Much of SolveCraft so far was written by AI coding agents (Claude) working in parallel, each
+owning one area, with a human setting direction and reporting bugs. Their working notes are in
+[AGENTS.md](AGENTS.md). Human contributors are just as welcome. Use whatever tools you like, as
+long as the change meets the rules above.
+
+## Where help is wanted most
+
+See the [`help wanted`](https://github.com/bherbruck/solvecraft/labels/help%20wanted) and
+[`good first issue`](https://github.com/bherbruck/solvecraft/labels/good%20first%20issue) labels.
+In order of how much they'd help users:
+
+1. **Fillet and blend robustness.** Fillets are our own code (truck has no fillet operation).
+ Constant, variable-radius and chord fillets work, and so do corners where fillets of
+ different radii meet, including three rounds meeting at a vertex. Next are setback corners, fillets along curved edges between curved
+ faces, and fillets that consume neighbouring faces.
+2. **Boolean robustness.** A random-design fuzzer currently gets about half of its designs
+ through without a kernel error. Each failing seed is a reproducible bug.
+3. **Y-up / Z-up.** SolveCraft is Z-up only, so most STEP files (from SolidWorks, Onshape, or
+ Fusion's default) open lying on their backs. Fusion solves this with a "default modeling
+ orientation" preference.
+4. **Imported appearances.** Colours from STEP files are lost when a feature changes the
+ imported body. They should become design appearances on import.
+5. **Drawings, CAM and mesh tools.** These are out of scope for now (see
+ [ROADMAP.md](ROADMAP.md)), but anyone who wants to own one is welcome.
+
+## Licence
+
+By contributing you agree that your contribution is licensed as MIT OR Apache-2.0, like the rest
+of SolveCraft. SolveCraft isn't affiliated with Autodesk. Fusion is a trademark of Autodesk, Inc.
diff --git a/README.md b/README.md
index baacc57d9e..7a66b91ca1 100644
--- a/README.md
+++ b/README.md
@@ -8,9 +8,11 @@ storytold "craft" family.
![SolveCraft with the sample plate](docs/screenshots/sample-plate.png)
-**Status: early (milestone M0 done, M1 in progress).** See [ROADMAP.md](ROADMAP.md),
-[docs/parity.md](docs/parity.md) (command parity with Fusion's Design workspace) and
-[docs/oracle.md](docs/oracle.md) (parts built in Fusion, rebuilt and measured in SolveCraft).
+**Status: early but usable for simple parts.** 76 of 76 reference parts built in Fusion
+rebuild in SolveCraft with the same volume, area and topology ([docs/oracle.md](docs/oracle.md));
+command parity with Fusion's Design workspace is tracked in [docs/parity.md](docs/parity.md).
+Open work and known bugs are in [GitHub issues](https://github.com/bherbruck/solvecraft/issues),
+and help is welcome: see [CONTRIBUTING.md](CONTRIBUTING.md).
## What works
@@ -98,6 +100,11 @@ configuration and an example session: [docs/mcp.md](docs/mcp.md).
| L5 | `ui-egui`, `mcp` | the swappable desktop front end; the MCP server (headless or bridged to the app) |
| apps | `solvecraft`, `solvecraft-cli` | desktop app, headless CLI |
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md): how to build and test, the code map, the clean-room
+and licence rules, and where help is wanted most.
+
## Licence
MIT OR Apache-2.0, at your option. SolveCraft is not affiliated with Autodesk; Fusion is a