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.
This commit is contained in:
Homero Thompson
2026-10-26 06:49:48 +00:00
committed by GitHub
parent 2a01cca00e
commit 3d0e2a8b3c
2 changed files with 13 additions and 1 deletions
+3 -1
View File
@@ -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
+10
View File
@@ -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