From d6200c9d532958f97f8b8a67faab0cfd1a85a541 Mon Sep 17 00:00:00 2001
From: Eric Gustin <34000337+EricGustin@users.noreply.github.com>
Date: Fri, 1 May 2026 15:43:41 -0700
Subject: [PATCH] chore: add PR template aligned with engineering standards
 (#835)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

Adds a PR template at `.github/PULL_REQUEST_TEMPLATE.md` encoding the 6
hard gates and section scaffolding from the 2026-04-24 engineering
announcement ("What a Good Pull Request Looks Like"), and lightly
updates `CONTRIBUTING.md` to point at it. The repo had no PR template;
recent PR descriptions have been inconsistent in structure and ticket
linking.

Resolves: _(driven by the 2026-04-24 engineering announcement; no Linear
ticket but happy to file one if preferred)_

## Design decisions

- Single template, not a multi-template directory.

## Scope

In scope:
- `.github/PULL_REQUEST_TEMPLATE.md` (new)
- `CONTRIBUTING.md` "Pull Request Guidelines" section (additive update;
existing 3 bullets preserved)

Not in scope:
- CI enforcement of template fields or ticket-linking

## Author checklist

- [x] `make check`/`make test` n/a — no Python touched; pre-commit hooks
pass
- [x] Reviewed my own diff top-to-bottom
- [x] I'd merge it myself

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> <sup>[Cursor Bugbot](https://cursor.com/bugbot) is generating a
summary for commit d1f15d1e6b1a7521d01ace3c1379b330767f1fb9. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
---
 .github/PULL_REQUEST_TEMPLATE.md | 87 ++++++++++++++++++++++++++++++++
 CONTRIBUTING.md                  |  4 ++
 2 files changed, 91 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 00000000..77cce647
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,87 @@
+<!--
+PR title: conventional commits with optional scope, e.g.
+  feat(arcade-core): add support for X
+  fix(arcade-mcp-server): handle stdio EOF
+  chore(arcade-tdk): bump dep
+
+Keep the title short and scannable. The description does the explaining.
+-->
+
+## Summary
+
+<!-- One short paragraph in plain English: what does this change do, and why? -->
+
+Resolves: <!-- Linear ticket link OR GitHub issue # (e.g. #123, or https://linear.app/...) -->
+
+## Design decisions
+
+<!--
+Delete this section if the change is mechanical.
+
+Call out non-obvious choices: why this approach, what alternatives you considered,
+what's intentionally NOT done. This is the part hardest to reconstruct from the
+diff and easiest to skip — write it anyway.
+-->
+
+## Scope
+
+<!--
+Delete this section if scope is obvious from the summary.
+
+In scope:
+-
+
+Not in scope (handled separately / out of band):
+-
+-->
+
+## Test plan
+
+<!--
+Concrete, verifiable steps — not "tests pass." Describe what you actually exercised.
+Example shape:
+
+- [ ] `make check` (ruff + mypy) clean
+- [ ] `make test` passes
+- [ ] Ran `arcade mcp stdio` against the example server and confirmed tools/list returns the expected entries
+- [ ] Exercised the end-user path: `arcade login` → tool call → confirmed auth token reached the tool
+- [ ] Verified the MCP stdio channel stayed clean (no stray stdout/stderr) per CLAUDE.md
+- [ ] Bumped the affected library version(s) in `libs/arcade-*/pyproject.toml` if the change is breaking
+-->
+
+- [ ]
+- [ ]
+
+## Risk note
+
+<!--
+Delete this section unless the PR touches a sensitive area.
+
+Sensitive paths in this repo include:
+- `libs/arcade-serve/` — worker JWT auth and `/worker/*` endpoints
+- `libs/arcade-mcp-server/arcade_mcp_server/resource_server.py` — OAuth 2.1 token validation
+- MCP stdio transport — any new stdout/stderr writes can corrupt the JSON-RPC channel
+- `pyproject.toml` files — version bumps, dependency changes, breaking-change semver
+- Tool secrets / env-var flow — anything reachable from `context.get_secret()`
+
+Describe the blast radius (who/what breaks if this is wrong) and your mitigations.
+-->
+
+## Coverage note
+
+<!--
+Delete this section unless patch coverage is in the yellow zone (70–85%).
+Aim for green (85%+); meaningful coverage matters more than artificial numbers.
+Why coverage is below green:
+-->
+
+## Author checklist
+
+Before moving this PR from Draft to Ready for Review:
+
+- [ ] Linked to a Linear ticket or GitHub issue (above)
+- [ ] I understand every change in the diff — not "an agent wrote it, I'm not sure why"
+- [ ] Runs locally, exercised through the end-user path (not just unit tests)
+- [ ] `make check` and `make test` are green locally; CI is expected to pass
+- [ ] I've pulled the branch fresh and reviewed my own diff top-to-bottom
+- [ ] I'd merge it myself if a teammate said LGTM right now
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ddf4300b..70cd51f3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -129,6 +129,10 @@ git push origin name-of-your-bugfix-or-feature
 
 # Pull Request Guidelines
 
+When you open a pull request, the [PR template](.github/PULL_REQUEST_TEMPLATE.md) will populate the description with prompts for a summary, ticket link, test plan, and a self-review checklist. Fill it in — it's the bar for moving from Draft to Ready for Review.
+
+In short: PRs should be small and focused, tested through the end-user path (not just unit tests), and self-reviewed before you mark them Ready. The reviewer is your customer — craft the PR so they can read, understand, and approve it on the first pass.
+
 Before you submit a pull request, check that it meets these guidelines:
 
 1. The pull request should include tests.