Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

chore(contributing): before/after evidence is mandatory, and enforced

Chaitanya Giri6e40337a522e
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index d04bd000..0f5e65d9 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -4,35 +4,71 @@ labels: ["bug"]
body:
- type: markdown
attributes:
- value: Thanks for taking the time to file a bug! Please fill out the sections below.
+ value: |
+ **A screenshot or recording is required.** We get more reports than we can
+ reproduce blind, and the ones with a picture get fixed first because they
+ are the ones we can actually see. If you can only give us one thing, give
+ us the recording.
- type: textarea
id: what-happened
attributes:
label: What happened?
- description: A clear description of the bug, plus what you expected instead.
+ description: What you saw, and what you expected instead.
validations:
required: true
- type: textarea
id: repro
attributes:
label: Steps to reproduce
+ description: Numbered steps, starting from a fresh launch. If we can't follow them, we can't fix it.
placeholder: |
- 1. Run `npm run dev`
+ 1. Launch the app
2. Add an agent with command `...`
3. See error
validations:
required: true
+ - type: textarea
+ id: evidence
+ attributes:
+ label: Screenshot or screen recording
+ description: |
+ **Required.** Drag the file straight into this box and GitHub will upload it.
+ A recording beats a still for anything that moves, hangs, or flickers.
+ If the bug is invisible on screen, show us the terminal or the log instead —
+ but show us something.
+ placeholder: Drag an image or video here.
+ validations:
+ required: true
- type: textarea
id: logs
attributes:
- label: Logs / screenshots
- description: Console output, stack traces, or a screenshot/clip if it's visual.
+ label: Logs / stack trace
+ description: Console output or a stack trace, if you have one. Paste as text, not a screenshot of text.
render: shell
+ - type: dropdown
+ id: os
+ attributes:
+ label: Operating system
+ options:
+ - macOS (Apple Silicon)
+ - macOS (Intel)
+ - Windows
+ - Linux
+ validations:
+ required: true
- type: input
- id: macos
+ id: os-version
attributes:
- label: macOS version
- placeholder: e.g. 15.0
+ label: OS version
+ placeholder: e.g. macOS 15.0, Windows 11 23H2, Ubuntu 24.04
+ validations:
+ required: true
+ - type: input
+ id: app-version
+ attributes:
+ label: Munder Difflin version
+ description: Settings → the version is on the hero card. Or `Munder Difflin → About`.
+ placeholder: e.g. 0.4.5
validations:
required: true
- type: input
@@ -43,16 +79,20 @@ body:
validations:
required: true
- type: input
- id: claude
+ id: agent-cli
attributes:
- label: Claude Code version (if relevant)
- placeholder: claude --version
+ label: Agent CLI and version (if relevant)
+ placeholder: e.g. claude --version, codex --version
- type: checkboxes
id: checks
attributes:
label: Pre-flight
options:
- - label: I re-ran `npm install` so `node-pty` is rebuilt for the current Electron ABI.
+ - label: I attached a screenshot or recording above.
+ required: true
+ - label: I'm on the latest release, or I've said above why I can't be.
+ required: true
+ - label: I re-ran `npm install` so `node-pty` is rebuilt for the current Electron ABI (source installs only).
required: true
- label: I searched existing issues and this isn't a duplicate.
required: true
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
index ba63b527..c9fb1879 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.yml
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -2,24 +2,45 @@ name: Feature request
description: Suggest an idea or improvement.
labels: ["enhancement"]
body:
+ - type: markdown
+ attributes:
+ value: |
+ **A picture is required here too.** Not a mockup of your idea necessarily —
+ a shot of the screen as it is today, with the gap in it. It is the fastest
+ way to make a proposal concrete, and it stops good ideas dying as prose.
+ Ideas still forming are better in
+ [Discussions](https://github.com/chaitanyagiri/munder-difflin/discussions).
- type: textarea
id: problem
attributes:
label: Problem / motivation
- description: What are you trying to do, and what's getting in the way?
+ description: What are you trying to do, and what's getting in the way? Describe the situation you hit, not the feature you want.
validations:
required: true
- type: textarea
id: proposal
attributes:
label: Proposed solution
- description: What would you like to see happen?
+ description: What should happen instead?
+ validations:
+ required: true
+ - type: textarea
+ id: evidence
+ attributes:
+ label: Screenshot, mockup or recording
+ description: |
+ **Required.** Drag the file straight into this box.
+ Any of these work: the screen today with the gap circled, a sketch of what
+ you mean, a recording of the workaround you're doing instead, or the same
+ thing done well in another app.
+ placeholder: Drag an image or video here.
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives considered
+ description: What you tried, or why the obvious approach doesn't work.
- type: dropdown
id: area
attributes:
@@ -30,7 +51,17 @@ body:
- The hive (memory, routing, GOD agent)
- Files / git
- Onboarding / config
+ - Updates / releases
- Design system
- Other
validations:
required: true
+ - type: checkboxes
+ id: checks
+ attributes:
+ label: Pre-flight
+ options:
+ - label: I attached a screenshot, mockup or recording above.
+ required: true
+ - label: I searched existing issues and discussions, and this isn't a duplicate.
+ required: true
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 4494d949..cd04d907 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,8 +1,15 @@
-<!-- Thanks for contributing to Munder Difflin! -->
+<!-- Thanks for contributing to Munder Difflin.
+
+ Read this line before you go further: a PR without a BEFORE and an AFTER
+ is not reviewable and will not be merged. The `PR evidence` check runs the
+ moment you open this and will tell you if it is missing. Keep the `Before`
+ and `After` headings below exactly as they are — the check reads them. -->
## What & why
-<!-- What does this change do, and why? Link any related issue: Closes #123 -->
+<!-- What changed, and why it needed to. Two or three sentences beats a
+ bullet list of file names — we can read the diff, we cannot read your
+ reasoning. If this fixes an issue, link it: Closes #123 -->
## Type of change
@@ -12,21 +19,52 @@
- [ ] Docs
- [ ] Build / CI
-## Screenshots / clips
+## Evidence
+
+<!-- REQUIRED. Drag images or a screen recording directly under each heading —
+ GitHub uploads them inline. Both headings must have something under them.
+
+ No visible UI? You still owe evidence. Record the failing behaviour and
+ then the same steps passing: a terminal capture, a log diff, a test that
+ goes from red to green. "It has no UI" is not an exemption.
+
+ Truly nothing observable, like a CI tweak or a typo? Say so in
+ "What & why" and ask a maintainer for the `no-visual-change` label. -->
+
+### Before
+
+<!-- The problem, as it exists on main right now. -->
+
+### After
+
+<!-- The same view or the same steps, with your change applied.
+ Same window size, same theme, same data — a reviewer should be able to
+ flip between the two and see only what you changed. -->
+
+## How I tested it
+
+<!-- The actual steps you ran, on which OS. Not "tested locally". -->
-<!-- REQUIRED for any visual change: a screenshot or short clip (before/after). -->
+- OS:
+- Steps:
## Discord (optional)
-<!-- If you'd like the `employee of the month` role in our Discord when this merges,
- put your handle below. Join first so we can find you: https://discord.gg/SEDzP5ZPk5 -->
+<!-- For the `employee of the month` role in our Discord when this merges.
+ Join first so we can find you: https://discord.gg/SEDzP5ZPk5 -->
-Discord:
+Discord:
## Checklist
-- [ ] `npm run typecheck` passes (the de-facto CI gate).
+- [ ] **Before and after evidence is attached above**, under both headings.
+- [ ] `npm run typecheck` passes.
+- [ ] `npm run test:focused` passes.
- [ ] `npm run build` succeeds.
-- [ ] Any new UI derives from `DESIGN.md` / `tokens.ts` — no ad-hoc colors, spacing, or fonts.
-- [ ] If I added art, it's my own or compatibly licensed, and listed in `ATTRIBUTION.md`.
-- [ ] PR is focused on a single change.
+- [ ] This PR is **one change**. Unrelated fixes belong in their own PR.
+- [ ] I read the diff myself before opening this, and there is no debug output,
+ commented-out code, or unrelated formatting churn in it.
+- [ ] Any new UI derives from `DESIGN.md` / `tokens.ts` — no ad-hoc colors,
+ spacing, or fonts.
+- [ ] If I added art, it's my own or compatibly licensed, and listed in
+ `ATTRIBUTION.md`.
diff --git a/.github/workflows/pr-evidence.yml b/.github/workflows/pr-evidence.yml
new file mode 100644
index 00000000..6a0582ce
--- /dev/null
+++ b/.github/workflows/pr-evidence.yml
@@ -0,0 +1,157 @@
+name: PR evidence
+
+# Every pull request must show its work: a BEFORE and an AFTER, as images or
+# video, in the PR description. This check is what makes that a rule rather than
+# a request — it turns the PR red and, with branch protection on, blocks merge.
+#
+# ── What this deliberately does NOT do ─────────────────────────────────────────
+# It cannot stop a PR being OPENED. Nothing on GitHub can; the API has no hook
+# that runs before creation. The strongest available enforcement is what this
+# does instead: fail within seconds of opening, block the merge button, and say
+# in a comment exactly what is missing. Re-edit the description and it re-runs.
+#
+# ── Why pull_request_target ────────────────────────────────────────────────────
+# Contributions come from forks, where `pull_request` hands the job a READ-ONLY
+# token, so it could never post the comment that tells someone what to fix.
+# `pull_request_target` runs with the base repo's token and write permission.
+# That is only safe under one condition, which this file obeys absolutely:
+#
+# NEVER check out, build, or execute the pull request's code here.
+#
+# This job reads two strings from the API — the PR body and its labels — and
+# nothing else. There is no `actions/checkout`, no `npm`, no run of any script
+# from the branch. Adding any of those to this file would hand a fork write
+# access to the repository. Put build steps in ci.yml, which is `pull_request`.
+on:
+ pull_request_target:
+ types: [opened, edited, reopened, synchronize, labeled, unlabeled]
+
+permissions:
+ pull-requests: write
+
+# A contributor fixing their description shouldn't queue behind their own
+# earlier runs — keep only the newest check per PR.
+concurrency:
+ group: pr-evidence-${{ github.event.pull_request.number }}
+ cancel-in-progress: true
+
+jobs:
+ evidence:
+ name: Before / after evidence
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/github-script@v7
+ with:
+ script: |
+ const pr = context.payload.pull_request;
+ const body = pr.body || '';
+ const labels = (pr.labels || []).map(l => l.name.toLowerCase());
+
+ // ── The maintainer escape hatch ──────────────────────────────────
+ // Some changes genuinely have nothing to show: a CI tweak, a typo, a
+ // dependency bump. A contributor CANNOT grant themselves this —
+ // applying a label needs write access — so the rule stays mandatory
+ // for the people it is aimed at, and every waiver is on the record.
+ const WAIVER = 'no-visual-change';
+ if (labels.includes(WAIVER)) {
+ core.info(`Waived: the '${WAIVER}' label is applied by a maintainer.`);
+ return;
+ }
+
+ // ── What counts as evidence ──────────────────────────────────────
+ // Anything a reader can actually SEE in the rendered description.
+ // A bare link to a file elsewhere does not count: it rots, it may be
+ // private, and it makes a reviewer leave the page.
+ const EVIDENCE = [
+ /!\[[^\]]*\]\([^)]+\)/, // ![alt](url)
+ /<img\b[^>]*\bsrc\s*=/i, // <img src=...>
+ /<video\b/i, // <video ...>
+ /https:\/\/github\.com\/user-attachments\/assets\/[\w-]+/i, // drag-and-drop (current)
+ /https:\/\/user-images\.githubusercontent\.com\/\S+/i, // drag-and-drop (legacy)
+ /https:\/\/\S+\.(png|jpe?g|gif|webp|mp4|mov|webm)\b/i // direct media link
+ ];
+ const hasEvidence = (text) => EVIDENCE.some(re => re.test(text));
+
+ // Comments are the template's own instructions to the author. Left
+ // unfilled they are invisible to a reader, so they must be invisible
+ // to this check too — otherwise the empty template would pass.
+ const visible = body.replace(/<!--[\s\S]*?-->/g, '');
+
+ // ── Before and after, separately ─────────────────────────────────
+ // Two assets in one blob is not the same as a before and an after.
+ // The template gives each its own heading; this reads the text under
+ // each heading up to the next one, so evidence has to sit in the
+ // right place to count for it.
+ const section = (name) => {
+ const re = new RegExp(
+ `^#{1,6}\\s*${name}\\b[^\\n]*\\n([\\s\\S]*?)(?=\\n#{1,6}\\s|$)`,
+ 'im'
+ );
+ return (visible.match(re) || [, ''])[1];
+ };
+
+ const before = section('before');
+ const after = section('after');
+
+ const missing = [];
+ if (!hasEvidence(before)) missing.push('**Before** — no image or video under that heading');
+ if (!hasEvidence(after)) missing.push('**After** — no image or video under that heading');
+
+ // A PR that kept the headings but put both assets in one place is a
+ // near miss, not a fresh offender. Say so, rather than repeating the
+ // generic rule at someone who is clearly trying.
+ const nearMiss = missing.length === 2 && hasEvidence(visible);
+
+ const MARKER = '<!-- pr-evidence-check -->';
+ const comments = await github.rest.issues.listComments({
+ owner: context.repo.owner, repo: context.repo.repo,
+ issue_number: pr.number, per_page: 100
+ });
+ const mine = comments.data.find(c =>
+ c.user.type === 'Bot' && (c.body || '').includes(MARKER));
+
+ if (missing.length === 0) {
+ // Clear the old complaint so a fixed PR doesn't keep wearing it.
+ if (mine) {
+ await github.rest.issues.updateComment({
+ owner: context.repo.owner, repo: context.repo.repo,
+ comment_id: mine.id,
+ body: `${MARKER}\n✅ **Evidence received.** Before and after are both attached. Thanks — this is what makes a PR reviewable in one pass.`
+ });
+ }
+ core.info('Before and after evidence both present.');
+ return;
+ }
+
+ const message = [
+ MARKER,
+ '### 🚫 This PR is missing its before/after evidence',
+ '',
+ nearMiss
+ ? 'You attached something, but not one under **each** heading. Both are required, and they have to sit under their own heading so a reviewer can tell which is which.'
+ : 'Every pull request here has to show its work. Screenshots or a short screen recording, **before the change and after it**.',
+ '',
+ ...missing.map(m => `- ${m}`),
+ '',
+ '**How to fix it:** edit the description, keep the `### Before` and `### After` headings from the template, and drag an image or video under each. GitHub uploads it inline. This check re-runs the moment you save.',
+ '',
+ 'A bug fix with no visible surface still needs it: show the failing behaviour, then the same steps passing. A terminal recording is fine.',
+ '',
+ `_Genuinely nothing to show — a CI tweak, a typo, a dependency bump? A maintainer can apply the \`${WAIVER}\` label. Please don't ask unless it truly has no observable effect._`,
+ '',
+ '📖 [CONTRIBUTING.md → Evidence is mandatory](https://github.com/chaitanyagiri/munder-difflin/blob/main/CONTRIBUTING.md#evidence-is-mandatory)'
+ ].join('\n');
+
+ if (mine) {
+ await github.rest.issues.updateComment({
+ owner: context.repo.owner, repo: context.repo.repo,
+ comment_id: mine.id, body: message
+ });
+ } else {
+ await github.rest.issues.createComment({
+ owner: context.repo.owner, repo: context.repo.repo,
+ issue_number: pr.number, body: message
+ });
+ }
+
+ core.setFailed(`Missing evidence: ${missing.length === 2 ? 'before and after' : missing[0].replace(/\*/g, '')}`);
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4b467c34..e11be8af 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -42,18 +42,78 @@ npm run dev # live-reloading Electron build
> re-run `npm install` (which re-triggers `postinstall`) after confirming your
> C/C++ toolchain is installed.
+## Evidence is mandatory
+
+**Every pull request must show a before and an after.** Screenshots, or a screen
+recording when the thing moves. They go in the PR description, under the
+`### Before` and `### After` headings the template gives you.
+
+This is enforced. The `PR evidence` check runs the moment you open a PR, and a
+PR that fails it does not merge. Fix the description and the check re-runs on
+save. It reads each heading separately, so two images dumped under one of them
+will not pass — a reviewer has to be able to tell which is which.
+
+**"My change has no UI" is not an exemption.** It changes the evidence, not the
+requirement:
+
+| Kind of change | What before/after looks like |
+|---|---|
+| Visual | The same view, twice. Same window size, same theme, same data. |
+| Bug fix | The bug happening, then the same steps not producing it. |
+| Terminal / CLI | A recording of the session, or the output pasted as text. |
+| Performance | The measurement before and the measurement after, same machine. |
+| Crash / hang | The failure, then the same path completing. |
+| Test-only | The suite red, then the suite green. |
+
+Make the two shots comparable. Different window sizes, a light shot against a
+dark one, or different data means the reviewer is diffing your screenshots
+instead of your change.
+
+The only way out is the `no-visual-change` label, which a maintainer applies
+for things with genuinely nothing observable: a CI tweak, a typo, a dependency
+bump. You cannot add it yourself, and asking for it on a change that does
+something visible will cost you more time than the screenshot would have.
+
## Before you open a PR
-1. **Keep the type-checker green:** `npm run typecheck` (runs both the node and
- web TS projects). This is the de-facto CI gate.
-2. **Run the tests:** `npm run test:focused` (the core suite), or
- `node --test test/*.test.cjs` to run everything in `test/`.
-3. **Confirm a production build works:** `npm run build`.
-4. **Match the aesthetic.** Any new UI **must** derive from the design tokens in
+1. **Attach the before and after.** See above. This is the one that gets PRs
+ closed unread, so do it first, not last.
+2. **Keep the type-checker green:** `npm run typecheck` (runs both the node and
+ web TS projects).
+3. **Run the tests:** `npm run test:focused`. If you changed behaviour, add a
+ test for it — a bug fix with no test is a bug fix that comes back.
+4. **Confirm a production build works:** `npm run build`.
+5. **Match the aesthetic.** Any new UI **must** derive from the design tokens in
[`DESIGN.md`](./DESIGN.md) / `src/renderer/src/design/tokens.ts` — no ad-hoc
colors, spacing, or fonts. `tokens.ts` and `tokens.css` are mirrored; if you
change one, change both.
-5. **For anything visual, include a screenshot or short clip** in the PR.
+6. **Read your own diff.** Every line of it. Debug logging, commented-out code,
+ and reformatting of files you didn't otherwise touch all get a PR sent back.
+
+## What gets a PR closed
+
+We are getting more pull requests than we can review carefully, so the bar has
+gone up. These are closed rather than negotiated:
+
+- **No before/after evidence**, and no `no-visual-change` label.
+- **More than one change in one PR.** A fix plus a refactor plus a rename is
+ three PRs. Split it and every one of them merges faster.
+- **Wholesale reformatting** of files, or a diff where the real change is buried
+ in whitespace and import reordering.
+- **A rewrite nobody asked for.** Large architectural changes need an issue or a
+ [discussion](https://github.com/chaitanyagiri/munder-difflin/discussions) with
+ agreement **before** you write the code. We would rather say no to a paragraph
+ than to a week of your work.
+- **Generated or unattributed content** — art that isn't yours or compatibly
+ licensed, or a description that doesn't match what the diff does.
+- **Dependency additions** that aren't justified in the description. A new
+ runtime dependency needs a reason a one-file helper wouldn't have solved.
+- **No response for 14 days** on review feedback. Reopen whenever you're ready;
+ nothing is lost.
+
+None of this is aimed at first-timers. A small, focused, well-evidenced PR from
+someone who has never contributed before gets reviewed ahead of a big one from
+someone who has.
## Project layout
@@ -78,9 +138,18 @@ data-flow overview.
## Commit & PR conventions
-- Branch off `main`; keep PRs focused on one change.
-- Write a clear PR description of *what* changed and *why*.
+- Branch off `main`. One change per PR — see
+ [What gets a PR closed](#what-gets-a-pr-closed).
+- Write a clear description of *what* changed and *why*. We can read the diff;
+ we cannot read your reasoning.
+- Say how you tested it, and on which OS. "Tested locally" tells us nothing.
+- Link the issue you're fixing: `Closes #123`.
- Don't commit `node_modules/`, `out/`, or built artifacts (already gitignored).
+- Don't force-push after a review has started. It throws away the comparison the
+ reviewer was working from.
+- **Never put credentials, tokens, internal metrics, or customer data in a
+ commit message.** A pushed commit message is public and permanent, and no
+ later rewrite retracts it once it has been fetched.
## A note on assets
diff --git a/README.md b/README.md
index cbaa87f7..5980e33a 100644
--- a/README.md
+++ b/README.md
@@ -313,6 +313,13 @@ Contributions are welcome — this is an early prototype with a lot of surface a
`npm run typecheck` green, and **derive any new UI from [`DESIGN.md`](./DESIGN.md) tokens**. Good
first areas: wiring real hook events, the add-agent flow, the config drawer, and cross-platform work.
+> [!IMPORTANT]
+> **Every pull request must show a before and an after** — screenshots, or a recording when the
+> thing moves — under the `### Before` and `### After` headings in the PR template. This is checked
+> automatically and a PR without it does not merge. "My change has no UI" is not an exemption; it
+> just changes what the evidence looks like. See
+> [Evidence is mandatory](./CONTRIBUTING.md#evidence-is-mandatory).
+
Questions, bugs, or want to show off your office? Join the Discord: **<https://discord.gg/SEDzP5ZPk5>**. Add your Discord handle to a PR and you'll get the `employee of the month` role when it merges.
## Telemetry