From 4ef5f10ce4937b4e7d7059de22cabf78b616437b Mon Sep 17 00:00:00 2001 From: Will Pfleger Date: Mon, 27 Jul 2026 08:57:09 -0700 Subject: [PATCH] docs(contributing): set PR expectations and require UI screenshots (#3140) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Follows up on the `CONTRIBUTING.md` refresh in #2780. With contributor volume up, the guide describes what a good PR looks like but never says what won't land or what happens after you open one. This closes those gaps in three additions, keeping the welcoming tone of the refresh: - **UI screenshot requirement** — a new item under "What a Good PR Looks Like": PRs changing desktop or mobile UI must include before/after screenshots (or a short recording). Also adds a one-line prompt to the PR template's Testing section. - **"PRs We're Unlikely to Merge"** — a short, positively-framed list (large refactors/dependency swaps without a prior issue, style-only churn, undiscussed new features, drive-by bundled changes) with a pointer to open an issue first. - **"What to Expect After You Open a PR"** — replaces the "Review Process" section: best-effort triage cadence, guide-skipping PRs may be closed with a pointer here, and a close isn't a rejection — address the gaps and reopen anytime. Retains the existing no-force-push and squash-merge guidance. ### Related issue N/A — follow-up to #2780; no duplicate PRs found. Signed-off-by: Will Pfleger --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- CONTRIBUTING.md | 29 +++++++++++++++++++++++++++-- 2 files changed, 28 insertions(+), 3 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 325a48510..238878c74 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -5,4 +5,4 @@ ### Testing - + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 87c12bf29..1f319fa20 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -284,9 +284,34 @@ required. The scope (in parentheses) is optional but encouraged. - How to test it manually (if applicable) - Any follow-up work deferred to a future PR -### Review Process +6. **Shows the UI** — any PR that changes the desktop or mobile UI includes + before/after screenshots (or a short recording for interactions) in the + description. We can't run every branch locally — screenshots let us review + UI changes same-day instead of waiting for someone to build your branch. -- We prioritize focused PRs that follow this guide and review as capacity allows. +### PRs We're Unlikely to Merge + +Some kinds of PRs usually get closed — not because they're bad ideas, but +because we can't safely review them without prior discussion: + +- **Large refactors or dependency swaps** without a prior issue agreeing on + the direction +- **Cosmetic renames or style-only churn** that doesn't fix a bug or improve + clarity +- **Entirely new features** with no prior discussion +- **Drive-by changes bundled into an unrelated fix** — split them out + +If you're considering any of these, open an issue first and we'll tell you +quickly whether it's a direction we'd merge. That saves your time as much as +ours. + +### What to Expect After You Open a PR + +- Maintainers triage new PRs on a best-effort cadence. Focused PRs that + follow this guide move fastest. +- Duplicates and PRs that skip this guide may be closed with a pointer here + rather than a full review. A close isn't a rejection of you or the idea — + address the gaps and reopen (or open a fresh PR) anytime. - Address review comments by pushing new commits (don't force-push during review; it makes it hard to see what changed). - Once approved, a maintainer will squash-merge your PR.