From 3d0e2a8b3cb7aad878e5f142b64f7e4a182a412c Mon Sep 17 00:00:00 2001 From: Homero Thompson Date: Mon, 26 Oct 2026 06:49:48 +0000 Subject: [PATCH] docs: the gate reads the working tree, and how to show a picture without committing it (#4902) * docs: two notes for agents and contributors (the gate's working tree, and linking a picture) * docs: how to show a picture without attaching it The reviewer asked for the pictures to be attached to the PR (or in a gist), not hosted on a branch of a fork, so the note no longer teaches the branch trick. * docs: say how to attach a picture, and what a gist is for The review of this pull request pointed at two things in the note on evidence: - Attaching works in the browser for anyone who can comment: drag the file into the comment. The limit is the command-line agent, whose upload needs write access to this repository. Say that, instead of claiming that a contributor without write access cannot attach a file. - A gist suits a log or another text file; it does not render a picture inline. Say what it is for, so nobody hits that dead end. The note in AGENTS.md about the gate reading the working tree is unchanged. --- AGENTS.md | 4 +++- CONTRIBUTING.md | 10 ++++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 83a73d4c3..3655c0860 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 dc4e385a0..4df32974e 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