open-design/.github/pull_request_template.md at 881571dea743d5e465feedb4a1b2dd7c6234e58c

mirror of https://github.com/nexu-io/open-design.git synced 2026-06-01 03:14:35 +07:00

docs(pr): require user-perspective description and surface area (#1520 )

* docs(pr): require user-perspective description and surface area

The previous template asked for Summary + Validation, which encouraged
code-perspective descriptions and let user-visible surface changes slip
past review unnoticed. Replace with:

- "Problem" — issue link + motivation
- "What users will see" — first-person user-visible effect
- "Surface area" — 9-item checklist (UI, shortcut, CLI/env, API/contract,
  extension point, i18n, top-level dependency, default behavior change, none)
- "Screenshots" — required when UI surface is checked, focused on the
  entry point users discover rather than the feature in isolation
- "Validation" — kept, retitled away from "Summary"

Authoritative rules added to AGENTS.md under a new "Pull request expectations"
section so external contributors' agents (Claude Code, Cursor, etc.) pick up
the requirement when reading the repo. CONTRIBUTING.md gets one pointer line
in "Commits & pull requests"; localized CONTRIBUTING variants (zh-CN, de, fr,
ja-JP, pt-BR) are left for follow-up translation PRs per the existing
docs-update workflow.

The existing "Fixes #" prompt is preserved verbatim — that template addition
from #1263 enforces PR-to-issue auto-linking and stays load-bearing.

* docs(pr): broaden dependency surface to dev deps as well

The "New top-level dependency" checkbox narrowed scope to runtime deps,
but CONTRIBUTING.md L239 says "No new top-level dependencies" without
limiting to runtime, and the AGENTS.md rule uses the same broad phrase.
A new devDependency (tool/test/build package) belongs in the same
bytes-vs-benefit explanation, so the checklist item should match.

* docs(pr): add Why and Bug fix verification; scope deps to root package.json

Three follow-up tweaks from review feedback:

1. Rename `## Problem` to `## Why` with a broader prompt that asks
   contributors to cover both their own use case (what made them write this
   PR today) and the pain being addressed. The old "Problem" framing only
   covered user-facing motivations and left no slot for the contributor's
   stake — a key signal for triaging external PRs.

2. New `## Bug fix verification` section between Screenshots and Validation,
   conditional on the PR being a bug fix. Surfaces the AGENTS.md
   "Bug follow-up workflow" red-spec requirement at PR-authoring time
   instead of leaving it implicit; asks for the test path and the
   red-on-main / green-on-branch confirmation.

3. Clarify the "New top-level dependency" checkbox to specify the **root**
   `package.json`. Without that word, contributors in a monorepo could read
   the check as applying to any workspace `package.json` (e.g. adding `react`
   to `apps/web/package.json` would be in scope) when CONTRIBUTING.md L239's
   "small on purpose" rule clearly meant root-level deps only.

AGENTS.md `## Pull request expectations` and CONTRIBUTING.md's pointer
line are updated to match the new section names and add the bug-fix
red-spec expectation.

2026-05-13 15:28:05 +08:00

3.4 KiB

Raw Blame History

Fixes #

Why

What users will see

Surface area

UI — new page / dialog / panel / menu item / setting / empty state in apps/web or apps/desktop (including Electron menu bar)
Keyboard shortcut — new or changed
CLI / env var — new od subcommand or flag, new tools-dev / tools-pack / tools-pr flag, or new OD_* env var
API / contract — new /api/* endpoint, new SSE event, or changed shape in packages/contracts
Extension point — new entry under skills/, design-systems/, design-templates/, or craft/, or change to the skills protocol
i18n keys — added new translation keys (see TRANSLATIONS.md for the locale workflow)
New top-level dependency — adding any new entry to the root package.json (dependencies or devDependencies); workspace-package package.json files are out of scope. Include a paragraph on what we get vs. what bytes we ship (see CONTRIBUTING.md → Code style)
Default behavior change — changes what existing users experience without opting in (default model, default setting, file/SQLite schema, auto-network on startup, auto-install)
None — internal refactor, docs, tests, or translation update only

3.4 KiB Raw Blame History

Why

What users will see

Surface area

Screenshots

Bug fix verification

Validation

3.4 KiB

Raw Blame History