From 276fe784d27ab2e194069aa5a57d979a9284453e Mon Sep 17 00:00:00 2001
From: Linus Rath <139418639+rathlinus@users.noreply.github.com>
Date: Fri, 2 Oct 2026 11:05:05 +0200
Subject: [PATCH] docs: add contribution scope and issue-first rules to the
 contributing guide

---
 .github/PULL_REQUEST_TEMPLATE.md | 21 +++++++++++++++++++++
 CONTRIBUTING.md                  | 12 ++++++++++++
 2 files changed, 33 insertions(+)
 create mode 100644 .github/PULL_REQUEST_TEMPLATE.md

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 000000000..827c40e31
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,21 @@
+## What and why
+
+<!-- What changes for the user, and why. A few sentences are enough. -->
+
+## Related issues
+
+<!-- "Fixes #123". For a change that needed agreement first, link the issue where the approach was agreed. -->
+
+## Checklist
+
+- [ ] The change fits [What fits in Bulwark](https://bulwarkmail.org/docs/development/contributing#what-fits-in-bulwark) (core, not plugin material)
+- [ ] It needed no issue first, or the approach was agreed in the linked issue (over ~500 lines excluding locales and tests, a new runtime dependency, or security-sensitive code: [details](https://bulwarkmail.org/docs/development/contributing#before-you-write-code))
+- [ ] `npm run typecheck && npm run lint && npx vitest run` pass, and new logic has tests
+- [ ] New user-facing text goes through translations
+- [ ] Works in Bulwark Lite, or is hidden there
+- [ ] UI changes checked at phone width and in the light and dark theme
+- [ ] Documentation updated in the [website repository](https://github.com/bulwarkmail/website/tree/main/docs), or not needed
+
+## Screenshots
+
+<!-- For UI changes: desktop and phone width. -->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 93b184e8e..ff3c3fb6a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,6 +4,18 @@ Bug reports, feature requests, translations and patches are all welcome.
 
 The full guide is in the documentation under [Contributing](https://bulwarkmail.org/docs/development/contributing). It covers the development setup, the test suites, translations and right-to-left layouts, code style, and how pull requests are reviewed.
 
+## What fits
+
+Read [What fits in Bulwark](https://bulwarkmail.org/docs/development/contributing#what-fits-in-bulwark) before you start on a feature. In short:
+
+- Bulwark is built for Stalwart. Changes for other JMAP servers are welcome if they cost Stalwart users nothing.
+- Core is for what most people expect from a mail, calendar, contacts and files client. Niche workflows and integrations with other services belong in plugins.
+- Not in core: IMAP or other non-JMAP backends, integrations with other services, Stalwart server administration, and changes to the look that go beyond themes.
+- New behaviour gets one good default. If deployments really need different behaviour, add an admin setting, not a per-user toggle.
+- Features must work in Bulwark Lite, or be hidden there, and UI changes must work at phone width.
+
+Open an issue and agree on the approach before you write a change that is larger than about 500 lines (not counting locales and tests), adds a runtime dependency, or touches sign-in, sessions, the HTML sanitizer, the plugin sandbox, outgoing-request guards or admin routes. Deliver large features as a series of pull requests that can each be reviewed on their own. Pull requests with review feedback unanswered for 30 days are closed.
+
 To get a development server running:
 
 ```bash