From c25e101b77b75ad94e3986fcf05da14e53ac42e5 Mon Sep 17 00:00:00 2001 From: Victor Santos Oliveira <56417388+Vittuu@users.noreply.github.com> Date: Sun, 18 Oct 2026 13:41:33 -0300 Subject: [PATCH] docs: align contribution guidance with current capabilities and CI (#2594) Thanks @Vittuu. --- CONTRIBUTING.md | 46 ++++++++++++++++++++++++---------------------- ROADMAP.md | 4 ++-- 2 files changed, 26 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b32dd8278..971144e4e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,9 @@ Help is welcome, whether that's a one-line fix or owning a whole area. This page build it, how the code is laid out, the few rules that aren't negotiable, and where help is needed most. +Before choosing a task, check the [command inventory](docs/features.md) and +[roadmap](ROADMAP.md) for implemented capabilities and current priorities. + Questions, ideas or want to say what you're working on? Join the [Discord](https://discord.gg/FtU4NQNVDH). ## Get it running (about 10 minutes on a fast machine) @@ -175,21 +178,24 @@ in the PR. `cargo xtask test` builds the tests with it and then runs every test `cargo xtask test -- shell`. Tests run beside each other on a busy machine, so a test must not depend on wall-clock timing. -**PRs test what they touch; main and nightly test everything.** On a pull request, CI maps the -changed files to workspace packages and runs Clippy, the test build and the tests for those and -the packages that depend on them (`scripts/ci/affected.py`, self-tested in the `checks` job). A -change to `Cargo.lock`, the root `Cargo.toml`, `.cargo/`, `.config/`, `.github/`, `vendor/`, -`tests/`, `scripts/` or any file outside a package runs the whole workspace, as does every push -to `main`, the nightly run and Run workflow. +**Ready pull requests test what they touch.** CI maps changed files to workspace packages and +runs Clippy, the test build and tests for those and their dependents. The +[package selector](scripts/ci/affected.py) and [CI workflow](.github/workflows/ci.yml) define +which changes require native checks; documentation, packaging and bot-script-only PRs can run +repository checks only. Workspace-wide changes, merge-queue groups, nightly runs and Run +workflow select the full workspace. A push to `main` reuses a successful merge-queue run for +the same commit; otherwise it runs the full suite. -**CI shards the tests.** One job builds them into a cargo-nextest archive and four jobs run a -quarter each, so every test runs in its own process: don't rely on state left by another test. -Pull requests skip a few heavy tests (one to four minutes each), which run on every push to -`main` and nightly; check the `main` run after merging. They are listed in +**CI shards the tests.** One job builds them into a cargo-nextest archive; two shards run on +pull requests and four during full validation. Every test runs in its own process: don't rely +on state left by another test. +Pull requests skip a few heavy tests (one to four minutes each), which run in full validation +(the merge queue, nightly, manual runs and pushes to `main` not already tested by the queue). +Check that validation after merging. They are listed in `.config/nextest.toml` and the [testing page](docs/book/src/dev/testing.md): - `solidcraft-engine`: `tests::hostile_params_never_panic`, everything in `tests::robustness` and - the seeds of `tests::robustness_goldens` (`seed_00` … `seed_95`; pull requests that touch `crates/kernel` run every 8th), + the seeds of `tests::robustness_goldens` (`seed_00` … `seed_95`; pull requests matching the workflow's geometry paths run all seeds), `pattern_suppress_tests::enclosure_arc_extinction_keeps_a_real_sharp_inner_lip_after_resize_and_reopen`, `pattern_suppress_tests::enclosure_datums_follow_wall_height_and_board_depth_with_material_proofs`, `cmd::plastic::tests::enclosure_snap_fit_follows_resized_front_wall`, the `atomic_commands` contract tests @@ -202,15 +208,16 @@ corpus of designs against a checked-in ratchet ([docs/action-matrix.md](docs/act A pull request that makes an action pass should record it with `cargo xtask action-matrix --bless`; one that makes a passing action fail fails the sample every CI run checks. -**The reference tests** are 76 parts in [`tests/oracle/`](tests/oracle/), each a `recipe.json` +**The reference tests** live in [`tests/oracle/`](tests/oracle/), each a `recipe.json` in our own format with an `expected.json` beside it. SolidCraft rebuilds the recipe and compares body count, volume, area, centre of mass and bounding box (and, where there is a `reference.stl`, the surface itself). Expected values are either worked out in closed form (`tools/oracle-analytic/`) or computed by building the same recipe in FreeCAD, run as a separate -program (`tools/freecad-oracle/`); each file says which. [docs/oracle.md](docs/oracle.md) has -the current results, and CI runs `cargo xtask oracle` on every pull request. A case that fails -because of a known bug names its issue in `expected.json` (`"known_failure": "#123"`); never -change an expected value to match SolidCraft's output. +program (`tools/freecad-oracle/`); each file says which. The generated +[reference test report](docs/oracle.md) has the current case count and results. The reference-test +CI job runs `cargo xtask oracle` during full validation; pull-request runs skip it. A case that +fails because of a known bug names its issue in `expected.json` (`"known_failure": "#123"`); +never change an expected value to match SolidCraft's output. ## Changing the design file format @@ -347,12 +354,7 @@ In order of how much they'd help users: 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.** SolidCraft 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 +3. **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 diff --git a/ROADMAP.md b/ROADMAP.md index 7c04725d3..e3ebd3811 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -9,7 +9,7 @@ features → parametric timeline) as an open, pure-Rust, agent-drivable applicat |---|---| | Where are we? | **M0 and M13 done; M1, M2, M5–M7, M9, M10, M14 in progress.** Sketch with solver and the full SKETCH create/modify set; extrude, revolve (two sides, symmetric, to object), fillet/chamfer (variable radius, chord length, a radius per edge, corner patches), holes, threads (cosmetic and modelled), patterns, mirror, shell (inside/outside/both), draft, loft, sweep, coil, split body and split face, delete face, construction planes, axes and points; persistent naming of faces and edges; parameters and configurations; components, joints, motion studies, exploded views; sheet metal and a plastic enclosure subset; STEP/IGES/3MF/STL/OBJ/DXF; FreeCAD/Rhino import; autosave and crash recovery; desktop and browser (wasm) app, CLI, MCP server. | | Features | Every registered command by area — [docs/features.md](docs/features.md) (`cargo xtask features`); registry breadth does not establish workflow or geometric depth | -| Reference tests | **82 / 82 parts match** — [docs/oracle.md](docs/oracle.md): public cases in `tests/oracle/` with analytic (61) or FreeCAD-computed (21) expected values, run by CI on every PR. | +| Reference tests | [Current case count and results](docs/oracle.md): public cases in `tests/oracle/` with analytic or FreeCAD-computed expected values, checked by the reference-test job in [CI](.github/workflows/ci.yml). | | Tests | Solver, profiles, kernel booleans/blends/measures, expressions, timeline, persistent naming, file formats and migrations, assemblies, sheet metal, engine end-to-end, hostile-input fuzz over every command and headless UI scenarios. `cargo xtask ci` reports the current passing counts. | | Gates | `cargo xtask ci`: fmt, clippy -D warnings, tests, asset attribution, layering, wasm32 build — green | | Time to a useful alpha (M0–M6) | ≈ **82 agent hours** remain (sum of the M1–M6 estimates below) | @@ -51,7 +51,7 @@ PCB / Package, Render, Animation, Simulation, Manufacture/CAM, Drawings. | M3 | General fillets and chamfers (curved edges, chains, vertex blends); saddle rolling-ball surfaces now use continuous seam sections and arc-length fitting with shared contact boundaries and bounded accuracy checks | in progress | 30 | | M4 | Files: STEP import (done — [docs/step-import.md](docs/step-import.md)), FreeCAD/Rhino solids through cadmpeg (done, desktop and CLI), 3MF export and 3MF/STL import as mesh bodies (done), 3MF with B-rep face tags ([docs/formats/3mf-face-tags.md](docs/formats/3mf-face-tags.md), done), constant-section parametric mesh reconstruction, DXF sketches, OBJ import | in progress | 6 | | M5 | Persistent naming of faces and edges (docs/book/src/dev/naming.md): faces named from their exact kernel-reported history (sketch curve sides, caps, revolve sections, primitive sides, blends, shell inner walls, pattern/mirror copies; split pieces told apart by the faces around them, lumps of a cut body named after their faces), edges by their faces; fillets/chamfers, sketches on faces, shell/draft/offset/replace faces, hole placements, joint origins and face appearances resolve by name first and warn when the entity split or vanished: done. sheet metal edges by base sketch line and flange side, shell inner faces, sweep and loft roles: done. kernel-reported face history: done (merged faces answer to every name; operations without history yet fall back to geometric names, flagged unverified; format 14 keeps older designs' geometric names). Left: history through sheet metal, plastic, surface and emboss features; FaceSource certificates through history | in progress | 20 | -| M6 | UI depth: selection feedback and origin (done), timeline editing (done: hover and selection highlight modifier faces, including fillets and chamfers; edit feature, history marker drag, dependency-checked single and multi-item reorder, suppress, rename, delete with dependents, re-resolved references; redefining selections refreshes persistent edge/face references while retaining feature identity and dimension names; optional compact named left feature history with rollback bar, multi-selection and persistent folders above the parts browser), right-docked dialogs (done), live previews for every feature dialog (done), keyboard-first commands with on-canvas value boxes and sketch inline dimensions (done), drag manipulators with automatic join/cut (done: extrude incl. two sides, fillet, shell, hole depth, move, pattern spacing, revolve rotator; taper handle open), dark theme (done), right-click menu with Repeat (done), measure tool (done), section analysis (done), selection filter (done), drag-solve of sketch points (done); appearance controls now preserve body/face/component targeting, named transparent looks, reuse/search and override removal; preferences | in progress | 6 | +| M6 | UI depth: selection feedback and origin (done), timeline editing (done: hover and selection highlight modifier faces, including fillets and chamfers; edit feature, history marker drag, dependency-checked single and multi-item reorder, suppress, rename, delete with dependents, re-resolved references; redefining selections refreshes persistent edge/face references while retaining feature identity and dimension names; optional compact named left feature history with rollback bar, multi-selection and persistent folders above the parts browser), right-docked dialogs (done), live previews for every feature dialog (done), keyboard-first commands with on-canvas value boxes and sketch inline dimensions (done), drag manipulators with automatic join/cut (done: extrude incl. two sides, fillet, shell, hole depth, move, pattern spacing, revolve rotator, extrude taper), dark theme (done), right-click menu with Repeat (done), measure tool (done), section analysis (done), selection filter (done), drag-solve of sketch points (done); appearance controls now preserve body/face/component targeting, named transparent looks, reuse/search and override removal; preferences | in progress | 6 | | M7 | Thin extrude (walls along open or closed curves: centre, inside, outside or two sides; mitred corners, crossing walls joined; #721), sweep, loft (incl. to a point), rib and web (to next / depth), emboss (planar faces and exact radial emboss/deboss of bounded orthogonal profiles on complete exterior cylinders/sleeves), thread (cosmetic, and modelled M3–M20 outside and inside: the ISO profile screwed in as a faceted cut), coil (smooth B-spline helical walls), pipe, pattern on path, patterns of bodies and components, replace face (parallel), align, remove, feature copy/paste: done. Unique eligible cylindrical targets are inferred for new Emboss features. Left: general curved-face emboss and exact (unfaceted) modelled threads | in progress | 12 | | M8 | Surface workspace (#772). Done: Patch (sketch regions; edge loops filled G0, plus `crown`), Stitch, Thicken (planes and cylinders), Extend (straight edges of planar surfaces), Trim (by a plane or a face), Delete Face (healing), Boundary Fill, zebra/draft/curvature-map analysis, Surface Extrude/Revolve/Sweep/Loft from open and closed curves, Offset, Unstitch and Reverse Normal; the continuity-driven core (`kernel/src/bridge.rs`, G0–G3 Hermite rows) with **Blend** (`surface.blend`, #764), **Match** (`surface.match`), **Boundary** (`surface.boundary`, #763 — two sketch curves exact with G0–G3, three or four as the flat patch of their loop, and curve networks: Coons and Gordon surfaces through sketch, 3D-sketch or edge curves, a point for a three-sided side, G1/G2 against the faces along one direction's edges, joined into their body on request; G1/G2 on two sides that meet at a corner waits for the Gregory-type corner), **Fair** (`surface.fair`, CV fairing), **continuity analysis** (`inspect.continuity`, #770; a toolbar tool with edge markers and a legend, and curvature combs along face isocurves) and a multi-section **loft** with per-end continuity and crown. Also in the Class-A pass: G1…G4 blend curves in the sketch, chord and variable-radius fillets on curved edges (with honest refusals where the fit cannot hold), and a G2 corner patch where filleted edges meet (kernel; the command refuses until the patch's sections can be sewn to the blends' contacts). Left: bias/form-factor fillet sections (design recorded), a Gregory-type corner, surface Fillet between separate surface bodies (#769), Ruled (#762), Untrim (#761), curved-face Extend (#760), loft guide rails (#201; sweep guide rails and two-rail sweeps are done, #771), and every remaining #757–#772 item | deferred | — | | M9 | Components and assemblies: New Component / Create Components from Bodies, active component, per-component origin/bodies/sketches/timeline entries, occurrences with transforms, Copy/Paste vs Paste New, nested Browser tree with visibility and isolate; Ground, Move/Copy of occurrences, joints (rigid, revolute, slider, cylindrical, pin-slot, planar, ball) by joint origins with limits and Drive Joints, closed kinematic loops (four-bar, slider-crank: the loop's other joints follow the driven one on its branch, and driving stops where a loop can no longer close), cams (`joint.cam`: a revolute cam drives a slider or revolute follower along a closed sketch profile or the cam's edges, knife, roller or flat followers, worked out again when the profile changes; drives, studies, closed loops, contact sets), As-built Joint, Rigid Group, Contact Sets (driving and motion studies stop where bodies in a set would pass through each other), Motion Study (joint values keyed along a timeline, playback, export of occurrence positions as JSON/CSV), motion analysis (joint values and a point's path charted over a study as value, velocity and acceleration; the parts that collide along a study, with the steps where they do), Exploded views (automatic or by hand, shown without changing placements); interference, per-component physical properties; STEP with assembly structure; URDF export for robot simulators (links with meshes, mass and inertia; joint chains whose values match Drive Joints; docs/urdf.md). Physical properties now measure material-aware component/occurrence placements, descendants and repeated instances, including pending moves and body reassignment offsets; contact geometry and automatic exploded centres respect those offsets. Groundwork done: component tree, occurrences with transforms (instances, Paste New), world placement, active component as authoring frame, ground, Capture/Revert Position, moving bodies and sketches. UI: ASSEMBLE panel dialogs for New Component, Joint (snaps on faces, edges, circles and vertices; animated motion preview; offsets, flip, limits), As-built Joint, Joint Origin, Rigid Group, Drive Joints (live slider), Motion Link, Cam and Interference (overlaps shown red); joints in the timeline and the Browser | in progress | 32 |