Skip to content

Commit 050f391

Browse files
FelixTJDietrichFelixTJDietrich
authored
docs(config): teach PR workflow to attach visual evidence (#1737)
1 parent 6992b9c commit 050f391

4 files changed

Lines changed: 86 additions & 44 deletions

File tree

‎.agents/skills/land-pr/SKILL.md‎

Lines changed: 36 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -105,24 +105,55 @@ the changeset, not the header.
105105
## 9. Open the PR
106106

107107
```bash
108-
PAGER=cat gh pr view --json number,url 2>/dev/null || PAGER=cat gh pr create --base main --title "<type>(<scope>): <description>" --body "$(cat <<'BODY'
109-
## Description
108+
PAGER=cat gh pr view --json number,url
109+
```
110+
111+
If that reports that the current branch has no pull request, create it:
112+
113+
```bash
114+
PAGER=cat gh pr create --base main --title "<type>(<scope>): <description>" --body "$(cat <<'BODY'
115+
## What changed and why
110116
111117
<1-2 sentences: what and why>
112118
113119
## How to test
114120
115121
<manual steps, or "CI covers this">
116122
117-
## Checklist
123+
## Release impact
124+
125+
<link the changeset and state operator action, or explain why neither applies>
126+
127+
## Notes for reviewers
128+
129+
<risks, tradeoffs, follow-up work, or delete this section>
130+
131+
## Visual evidence
118132
119-
<the items from .github/PULL_REQUEST_TEMPLATE.md that apply>
133+
<UI: before and after. Motion or timing: a short video. Otherwise delete this section.>
120134
BODY
121135
)"
122136
```
123137

124-
## 10. Verify
138+
## 10. Upload visual evidence
139+
140+
For a UI change, save PR-only evidence under the ignored `tmp/` directory and inspect it for
141+
secrets, personal data, and unrelated content. Give each image alt text that describes the visible
142+
state. For a video, describe the demonstrated behavior in the PR body.
143+
144+
```bash
145+
mkdir -p tmp
146+
gh pr edit --attach './tmp/before.png#Settings before the change' --attach './tmp/after.png#Settings after the change'
147+
```
148+
149+
An upload can add earlier files before a later file fails. Inspect the PR before retrying, then
150+
attach only the missing files.
151+
152+
## 11. Verify
125153

126154
```bash
127155
PAGER=cat gh pr view --json url,title -q '"PR: \(.title)\nURL: \(.url)"'
128156
```
157+
158+
Open the URL and check that every attachment renders, describes the intended state, and contains no
159+
sensitive or unrelated content.

‎.claude/skills/land-pr/SKILL.md‎

Lines changed: 36 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -105,24 +105,55 @@ the changeset, not the header.
105105
## 9. Open the PR
106106

107107
```bash
108-
PAGER=cat gh pr view --json number,url 2>/dev/null || PAGER=cat gh pr create --base main --title "<type>(<scope>): <description>" --body "$(cat <<'BODY'
109-
## Description
108+
PAGER=cat gh pr view --json number,url
109+
```
110+
111+
If that reports that the current branch has no pull request, create it:
112+
113+
```bash
114+
PAGER=cat gh pr create --base main --title "<type>(<scope>): <description>" --body "$(cat <<'BODY'
115+
## What changed and why
110116
111117
<1-2 sentences: what and why>
112118
113119
## How to test
114120
115121
<manual steps, or "CI covers this">
116122
117-
## Checklist
123+
## Release impact
124+
125+
<link the changeset and state operator action, or explain why neither applies>
126+
127+
## Notes for reviewers
128+
129+
<risks, tradeoffs, follow-up work, or delete this section>
130+
131+
## Visual evidence
118132
119-
<the items from .github/PULL_REQUEST_TEMPLATE.md that apply>
133+
<UI: before and after. Motion or timing: a short video. Otherwise delete this section.>
120134
BODY
121135
)"
122136
```
123137

124-
## 10. Verify
138+
## 10. Upload visual evidence
139+
140+
For a UI change, save PR-only evidence under the ignored `tmp/` directory and inspect it for
141+
secrets, personal data, and unrelated content. Give each image alt text that describes the visible
142+
state. For a video, describe the demonstrated behavior in the PR body.
143+
144+
```bash
145+
mkdir -p tmp
146+
gh pr edit --attach './tmp/before.png#Settings before the change' --attach './tmp/after.png#Settings after the change'
147+
```
148+
149+
An upload can add earlier files before a later file fails. Inspect the PR before retrying, then
150+
attach only the missing files.
151+
152+
## 11. Verify
125153

126154
```bash
127155
PAGER=cat gh pr view --json url,title -q '"PR: \(.title)\nURL: \(.url)"'
128156
```
157+
158+
Open the URL and check that every attachment renders, describes the intended state, and contains no
159+
sensitive or unrelated content.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 12 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,23 @@
1-
<!--
2-
TITLE FORMAT (required):
3-
<type>(<scope>): <description>
1+
<!-- Thanks for contributing. Use the title format in CONTRIBUTING.md and delete sections that do not apply. -->
42

5-
Types and scopes: CONTRIBUTING.md § Pull Request Title Guidelines (validated by commitlint.config.ts).
6-
Breaking changes are carried by the changeset (pre-1.0: minor + **Operators:** + .migration/<slug>.md), not the title.
3+
## What changed and why
74

8-
✓ Good: feat(leaderboard): add weekly ranking filter
9-
✓ Good: fix(ci): update workflow configuration
10-
✗ Bad: Added weekly ranking filter to leaderboard
5+
<!-- Start with the problem, then explain the solution and why this approach is appropriate. -->
116

12-
BEFORE PUSHING:
13-
pnpm run format && pnpm run check # Apply formatting, then run the local quality gate
14-
15-
AFTER API CHANGES:
16-
pnpm run generate:api # Rewrites server/openapi.yaml and webapp/src/api
17-
18-
AFTER DATABASE/ENTITY CHANGES:
19-
pnpm run db:draft-changelog # Writes this branch's changelog (needs Docker); prune it, add preconditions and rollbacks
20-
pnpm run db:generate-erd-docs # After pruning
21-
-->
22-
23-
## Description
24-
25-
<!-- 1-2 sentences: what changed, and why. -->
26-
27-
Fixes # <!-- Link issue if applicable, or delete this line -->
7+
<!-- Link related work with "Fixes #123" when merging this PR should close it. -->
288

299
## How to test
3010

31-
<!-- Manual steps to verify, OR "CI covers this" for config/docs changes. -->
11+
<!-- List the behavior you exercised and the exact steps or commands needed to reproduce it. -->
12+
13+
## Release impact
3214

33-
## Checklist
15+
<!-- Link the changeset and state any operator action. If neither applies, explain why. -->
3416

35-
<!-- Only what CI can't check for you. Changeset presence is enforced by `verify-changesets`. -->
17+
## Notes for reviewers
3618

37-
- [ ] My changeset summary reads as an operator/user-facing note (it becomes the changelog entry) — see `.changeset/README.md`
38-
- [ ] If operators must act, the changeset and migration fragment state what the operator must do
39-
- [ ] I did not commit generated-artifact changes that this PR did not cause
19+
<!-- Call out risks, tradeoffs, follow-up work, or the best place to begin reviewing. Delete if unnecessary. -->
4020

41-
## Screenshots
21+
## Visual evidence
4222

43-
<!-- For UI changes. Delete section if not applicable. -->
23+
<!-- UI changes: show before and after. Motion or timing changes: add a short video. Delete otherwise. -->

‎AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -203,8 +203,8 @@ Oxlint lints; oxfmt formats and sorts imports. Each tree states its rule set in
203203
change is carried by the changeset.
204204
- Body: the problem in a sentence or two, then how you fixed it and how you verified it. End with
205205
the model and harness that did the work. `.github/PULL_REQUEST_TEMPLATE.md` is the shape.
206-
- UI changes need before/after images; motion or timing needs a short video. Upload evidence to
207-
GitHub; never commit screenshots or PR-only assets.
206+
- UI changes need before/after images; motion or timing needs a short video. Never commit PR-only
207+
evidence; `/land-pr` owns its preparation and upload.
208208
- One concern per PR. If the description says "also", split it.
209209
- A PR that changes shipped code ships a changeset — `.changeset/README.md` is the contract. With no
210210
TTY, hand-write `.changeset/<slug>.md` in the shape shown there; `verify-changesets` fails the PR

0 commit comments

Comments
 (0)