diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index ba6bb8093..d66755db0 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,6 +1,6 @@ ## Change -Describe the problem and resulting behavior. Link the issue when applicable. +Start with what this is, in plain words someone new to the project would understand: what it does and who it's for. Don't assume anyone knows the name of your tool, project or feature. Then describe the problem and resulting behavior. Link the issue when applicable. Changes a default: no @@ -14,6 +14,8 @@ What did you run, and what were the results? Include expected and measured value ## Screenshots of the behavior (when observable) +Put the picture or video here in the description. A file in the diff doesn't count: a maintainer has to be able to see what this is without opening the changed files. + For observable CAD, UI or model behavior, include actual descriptive screenshots or a short recording from a small reproduction. This includes kernel, geometry, assembly and backend effects that can be shown in the app. Coding agents should run the app and capture the evidence themselves, rather than asking a human for evidence they can produce. Show the actual failure/result, preferably before and after, with brief steps, expected/actual behavior and annotations where helpful. Flowcharts and Mermaid diagrams cannot substitute for evidence of visible behavior. Use diagrams for architectural reasoning when actual screenshots cannot illustrate the point. Changes with no useful observable behavior may omit screenshot/video evidence. Exclude private designs and sensitive details; attach media or link to an accessible recording rather than committing generated review artifacts. diff --git a/.github/workflows/pr-checks.yml b/.github/workflows/pr-checks.yml index 2650b1ec5..c54957046 100644 --- a/.github/workflows/pr-checks.yml +++ b/.github/workflows/pr-checks.yml @@ -1,6 +1,6 @@ -# Two quick checks on every pull request (CONTRIBUTING.md, "Sending a change"): no second open PR -# for an issue a lower-numbered one already closes, and the "Changes a default:" line is filled in. -# Neither is a required status check. The logic is in scripts/pr-checks/pr-checks.js (tested in ci.yml). +# Three quick checks on every pull request (CONTRIBUTING.md, "Sending a change"): no second open PR +# for an issue a lower-numbered one already closes, the "Changes a default:" line is filled in, and +# a PR adding to the showcase shows a picture. None is a required status check. The logic is in scripts/pr-checks/pr-checks.js (tested in ci.yml). name: PR checks on: @@ -48,6 +48,21 @@ jobs: const r = await checks.checkDefaults({ github, context, core }); core.info(JSON.stringify(r)); + picture: + name: Picture check + runs-on: ubuntu-24.04 + timeout-minutes: 5 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + sparse-checkout: scripts/pr-checks + - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 + with: + script: | + const checks = require('./scripts/pr-checks/pr-checks.js'); + const r = await checks.checkPicture({ github, context, core }); + core.info(JSON.stringify(r)); + # Labelling needs write access, which a fork PR's token never has, so it is its own job and best # effort: a fork PR just doesn't get the `changes-default` label from here. label: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 54fed4165..24ed0d02f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -347,6 +347,13 @@ without pushes. These automatic cleanup deadlines are separate from the daily pr `/unclaim` releases the bot claim early (only you or a maintainer can). Issues a maintainer has taken are never freed automatically. +**A PR has to explain itself.** Start the description with what it is, in plain words someone new +to the project would understand: what it does and who it's for. Don't assume anyone knows the name +of your tool, project or feature. If there's anything to look at, show it in the description: a +picture or video has to be visible there without opening the changed files. "The GIF is the change" +doesn't count. A PR that doesn't do this waits until it does. For a PR that adds to +`docs/showcase.md` or `docs/screenshots/`, the Picture check fails until the description shows one. + Help reviewers see what the words mean. For observable CAD, UI or model behavior, please include actual descriptive screenshots or a short recording in the issue or PR. This evidence is required for changes or bugs that can be demonstrated in the app, including kernel, diff --git a/scripts/pr-checks/pr-checks.js b/scripts/pr-checks/pr-checks.js index 06ff60113..781c64271 100644 --- a/scripts/pr-checks/pr-checks.js +++ b/scripts/pr-checks/pr-checks.js @@ -1,7 +1,8 @@ // Pull request checks for .github/workflows/pr-checks.yml (CONTRIBUTING.md, "Sending a change"): // 1. duplicate: fails when a lower-numbered open PR already closes the same issue; // 2. defaults: the template line `Changes a default: no | yes - , old behaviour kept behind -// preference ` must be present and well formed; `yes` earns the `changes-default` label. +// preference ` must be present and well formed; `yes` earns the `changes-default` label; +// 3. picture: a PR adding to the showcase or docs/screenshots shows a picture in its description. // The parsing is pure and tested in scripts/pr-checks/pr-checks.test.js; the functions that talk to // GitHub take the github-script `github` client and `context`, so the tests can pass fakes. 'use strict'; @@ -10,6 +11,11 @@ const SKIP_LABEL = 'not-a-duplicate'; const DEFAULT_LABEL = 'changes-default'; // PRs opened before this predate the template line; they pass the defaults check with a notice. const DEFAULTS_ENFORCED_FROM = Date.parse('2026-10-25T00:00:00Z'); +// PRs opened before this predate the picture rule; they pass the picture check with a notice. +const PICTURE_ENFORCED_FROM = Date.parse('2026-11-02T00:00:00Z'); +const PICTURE_HELP = + 'Show it in the description: drag a picture or video into the PR text so it can be seen without ' + + 'opening the changed files, and say in plain words what it is (CONTRIBUTING.md, "Sending a change").'; const BOT_LOGINS = new Set(['dependabot[bot]', 'github-actions[bot]', 'dependabot-preview[bot]']); // Template comments and code blocks hold examples, not claims. @@ -106,6 +112,33 @@ async function checkDuplicate({ github, context, core }) { return { dups }; } +// A picture or video someone can see in the description: not one in a comment, a code block or the +// template's own text. +function hasPicture(body) { + const text = stripNoise(body); + return /!\[[^\]]*\]\([^)\s]+[^)]*\)/.test(text) + || /<(?:img|video)\b[^>]*\bsrc=/i.test(text) + || /https:\/\/github\.com\/user-attachments\/assets\/\S+/.test(text); +} + +// Files that are about something to look at, whatever the rest of the PR does. +function needsPicture(files) { + return files.some((f) => f === 'docs/showcase.md' || f.startsWith('docs/screenshots/')); +} + +async function checkPicture({ github, context, core }) { + const pull = context.payload.pull_request; + if (isBot(pull.user)) return { skipped: 'bot' }; + if (!(Date.parse(pull.created_at) >= PICTURE_ENFORCED_FROM)) return { skipped: 'opened before enforcement' }; + const files = (await github.paginate(github.rest.pulls.listFiles, { + ...context.repo, pull_number: pull.number, per_page: 100, + })).map((f) => f.filename); + if (!needsPicture(files)) return { skipped: 'nothing to show' }; + const shown = hasPicture(pull.body); + if (!shown) core.setFailed(`This PR adds something to look at, but the description shows no picture. ${PICTURE_HELP}`); + return { shown }; +} + async function checkDefaults({ github, context, core }) { const pull = context.payload.pull_request; if (isBot(pull.user)) return { skipped: 'bot' }; @@ -149,4 +182,5 @@ async function syncDefaultLabel({ github, context, core }) { module.exports = { DEFAULTS_ENFORCED_FROM, SKIP_LABEL, DEFAULT_LABEL, stripNoise, parseClosing, parseDefaults, isBot, isDocsOnly, findDuplicates, checkDuplicate, checkDefaults, syncDefaultLabel, + PICTURE_ENFORCED_FROM, hasPicture, needsPicture, checkPicture, }; diff --git a/scripts/pr-checks/pr-checks.test.js b/scripts/pr-checks/pr-checks.test.js index b64b984f2..c3e479ef4 100644 --- a/scripts/pr-checks/pr-checks.test.js +++ b/scripts/pr-checks/pr-checks.test.js @@ -158,3 +158,39 @@ test('checkDefaults only enforces from 2026-10-25', async () => { await pc.checkDefaults(f); assert.equal(f.failures.length, 1); }); + +test('hasPicture needs one a reader can see in the description', () => { + assert.equal(pc.hasPicture('![tray](https://example.com/a.gif)'), true); + assert.equal(pc.hasPicture('x'), true); + assert.equal(pc.hasPicture(''), true); + assert.equal(pc.hasPicture('https://github.com/user-attachments/assets/abc'), true); + assert.equal(pc.hasPicture(''), false); + assert.equal(pc.hasPicture(null), false); + assert.equal(pc.hasPicture('The GIF is the change.'), false); + assert.equal(pc.hasPicture('See docs/screenshots/box.gif'), false); + assert.equal(pc.hasPicture(''), false); + assert.equal(pc.hasPicture('```\n![x](https://example.com/a.gif)\n```'), false); + assert.equal(pc.hasPicture('`![x](https://example.com/a.gif)`'), false); +}); + +test('needsPicture covers the showcase and its media only', () => { + assert.equal(pc.needsPicture(['docs/showcase.md']), true); + assert.equal(pc.needsPicture(['crates/a.rs', 'docs/screenshots/a.gif']), true); + assert.equal(pc.needsPicture(['docs/mcp.md', 'crates/a.rs']), false); +}); + +test('checkPicture fails a showcase PR with no picture, from 2026-11-02 on', async () => { + const files = [{ filename: 'docs/showcase.md' }]; + const pr = mk(30, 'alice', 'The GIF is the change.', { created_at: '2026-11-02T00:00:00Z' }); + let f = fakes(pr, { files }); + assert.deepEqual(await pc.checkPicture(f), { shown: false }); + assert.equal(f.failures.length, 1); + f = fakes({ ...pr, body: '![it](https://example.com/a.gif)' }, { files }); + assert.deepEqual(await pc.checkPicture(f), { shown: true }); + assert.equal(f.failures.length, 0); + f = fakes({ ...pr, created_at: '2026-11-01T23:59:59Z' }, { files }); + assert.deepEqual(await pc.checkPicture(f), { skipped: 'opened before enforcement' }); + f = fakes(pr, { files: [{ filename: 'crates/a.rs' }] }); + assert.deepEqual(await pc.checkPicture(f), { skipped: 'nothing to show' }); + assert.equal(f.failures.length, 0); +});