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:
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user