From 20f39dceb3a7f80f32e8b4691f397a9d1fb3b437 Mon Sep 17 00:00:00 2001
From: Jac Fitzgerald <jac.fitzgerald@salesforce.com>
Date: Sat, 8 Aug 2026 01:38:03 -0700
Subject: [PATCH 1/2] docs: add pull-request template with Motivation /
 Behavior / Test plan

Reviewers of PRs to this repo have to guess "why now" for most changes,
whether a PR is a behavior change for downstream users, and which
claims in the body are covered by tests vs. verified manually. Adding
a template with three prompts lets contributors surface those answers
without me nagging in every review.

The sections are opinionated but small: Motivation, Behavior change,
and Test plan. Each has a comment explaining the intent. Contributors
can delete sections that don't apply.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .github/PULL_REQUEST_TEMPLATE.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 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..1c3eb9ccd
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,31 @@
+<!--
+Delete sections that don't apply. The prompts are here to make review
+faster, not to add ceremony -- one sentence per section is often enough.
+-->
+
+## Motivation
+
+<!--
+Why now. Link the issue, incident, user report, or parent PR. If this
+is preparation for another change, name it. If it's cleanup, say what
+prompted it.
+-->
+
+## Behavior change
+
+<!--
+For users of the library or CLI: what changes in observable behavior?
+"None -- refactor only" is a valid answer. If a public symbol, endpoint
+signature, exception type, or return value shape changes, call it out
+here and in the CHANGELOG so downstream code isn't surprised.
+-->
+
+## Test plan
+
+<!--
+What's exercised by the tests in this PR. If any behavior claim in the
+description ISN'T covered by a test (e.g. "verified manually against a
+live server", "matches server behavior at REST endpoint X"), say so
+explicitly so reviewers know what's on trust vs. what regression tests
+will catch.
+-->

From 6c99c796b6bab6697fc0f01f4191466b89f580f7 Mon Sep 17 00:00:00 2001
From: Jac Fitzgerald <jac.fitzgerald@salesforce.com>
Date: Tue, 18 Aug 2026 01:12:32 -0700
Subject: [PATCH 2/2] Address fresh-eyes review on PR template

Two nits from review:
- Swap literal `--` inside HTML comments for single `-`. GitHub renders
  both fine, but double-dash is invalid SGML inside a comment and some
  markdown linters flag it.
- Add a one-line pointer to contributing.md and CHANGELOG.md so external
  contributors don't have to hunt for the CHANGELOG expectation.
---
 .github/PULL_REQUEST_TEMPLATE.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 1c3eb9ccd..5d042a9b8 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,6 +1,8 @@
 <!--
 Delete sections that don't apply. The prompts are here to make review
-faster, not to add ceremony -- one sentence per section is often enough.
+faster, not to add ceremony - one sentence per section is often enough.
+See contributing.md for background; add a bullet to CHANGELOG.md under
+Unreleased for any user-visible behavior change.
 -->
 
 ## Motivation
@@ -15,7 +17,7 @@ prompted it.
 
 <!--
 For users of the library or CLI: what changes in observable behavior?
-"None -- refactor only" is a valid answer. If a public symbol, endpoint
+"None - refactor only" is a valid answer. If a public symbol, endpoint
 signature, exception type, or return value shape changes, call it out
 here and in the CHANGELOG so downstream code isn't surprised.
 -->