Skip to content

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

docs: the gate reads the working tree, and how to show a picture without committing it (#4902)

Homero Thompson3d0e2a8b3cb7
diff --git a/AGENTS.md b/AGENTS.md
index 83a73d4c35..3655c0860b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -117,7 +117,9 @@ People trust SolidCraft with their designs; a crash loses their work. **This out
run service workers as JavaScript) and the small inline scripts in `apps/solidcraft-web/index.html`.
Keep them minimal; `cargo xtask web-offline-test` covers the service worker.
- **Quality gates** before every commit: `cargo xtask ci` (fmt, clippy -D warnings, tests,
- assets, layers). Commit after every feature arc that builds.
+ assets, layers). Commit after every feature arc that builds. The gate reads the working tree,
+ so do not switch branches while it runs: it compiles the other branch's code and fails on a
+ change that is not in the PR. Run it in the background and wait for its log.
- **Publishing**: the repository is github.com/tangency-labs/solidcraft. Changes land through
**pull requests** and the **merge queue**: push a branch and open a PR. The heavy CI jobs start
when a maintainer adds `approved-for-ci` after reviewing the code. Approved PRs go into the queue
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index dc4e385a0f..4df32974eb 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -339,6 +339,16 @@ Changes with no useful observable behavior do not need screenshot or video evide
small example without private designs or sensitive details; attach the media or link to an
accessible recording rather than committing generated review artifacts.
+To show a picture without committing it, attach the media to the PR (it goes to the PR's own
+attachment storage and renders inline in the comment). A gist is the better home for a log or
+another text file, and you link it; a gist does not render a picture inline. The review artifacts
+stay out of the diff that way, and nothing has to be pushed to a branch of its own.
+
+Attaching works in the browser for anyone who can comment: drag the file into a comment on the
+pull request. A command-line agent without a browser session usually cannot attach a file (the
+upload needs write access to this repository). Say so in the pull request, and the person running
+the agent or a maintainer can attach it.
+
Keep an eye on your PR's status, but don't push to it only to catch up with `main` (no merge of
`main`, no Update branch button, no rebase for that alone): every push restarts the whole CI
run for everyone waiting behind it, and `main`'s own run catches what lands in between. When you