From 982a07130ec5896f10924984ba26109083983381 Mon Sep 17 00:00:00 2001
From: julianz- <6255571+julianz-@users.noreply.github.com>
Date: Sun, 5 Jul 2026 02:06:13 -0700
Subject: [PATCH] Update contribution guidelines in pull request template

Revise the PR template incorporating elements from webknjaz's
tox-towncrier template, adding a warning block with mandatory
contribution rules, a changelog entry checkbox linking to the fragment
guidelines, improved commit message guidance, and updated reference links.
---
 .github/PULL_REQUEST_TEMPLATE.md           | 64 +++++++++++++++-------
 docs/changelog-fragments.d/834.contrib.rst |  4 ++
 2 files changed, 49 insertions(+), 19 deletions(-)
 create mode 100644 docs/changelog-fragments.d/834.contrib.rst

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index bdeee9949d..1200e0d43e 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,4 +1,14 @@
-❓ **What kind of change does this PR introduce?**
+<!--
+  Thank you for your contribution!
+  Please use our PR template — PRs that strip it will not be reviewed.
+
+  Before submitting, please ensure you have:
+  - Added a change log fragment in docs/changelog-fragments.d/ (see the link in the checklist below)
+  - Written commits with a clear title and a body explaining the why
+  - Avoided letting an AI agent strip or overwrite the fields below
+-->
+
+## What kind of change does this PR introduce?
 
 * [ ] 🐞 bug fix
 * [ ] 🐣 feature
@@ -7,41 +17,57 @@
 * [ ] 📋 refactoring
 * [ ] 💥 other
 
-📋 **What is the related issue number (starting with `#`)**
-
-<!-- Are there any issues opened that will be resolved by merging this change? -->
-Resolves #<!-- issue number here -->
+## What do these changes do?
 
-❓ **What is the current behavior?** (You can also link to an open issue here)
+<!-- Please give a short brief about these changes. -->
 
+## Are there changes in behavior for the user?
 
+<!-- Outline any notable behavior for the end users. -->
 
-❓ **What is the new behavior (if this is a feature change)?**
+## Is it a substantial burden for the maintainers to support this?
 
+<!--
+Stop right there! Pause. Just for a minute... Can you think of anything
+obvious that would complicate the ongoing development of this project?
 
+Try to consider if you'd be able to maintain it throughout the next
+5 years. Does it seem viable? Tell us your thoughts! We'd very much
+love to hear what the consequences of merging this patch might be...
 
-📋 **Other information**:
+This will help us assess if your change is something we'd want to
+entertain early in the review process. Thank you in advance!
+-->
 
+## Related issue number
 
+<!-- Will this resolve any open issues? -->
+<!-- Remember to prefix with 'Fixes' if it closes an issue (e.g. 'Fixes #123'). -->
 
-📋 **Contribution checklist:**
-
-(If you're a first-timer, check out
-[this guide on making great pull requests][making a lovely PR])
+## Checklist
 
 * [ ] I wrote descriptive pull request text above
+* [ ] The PR relates to *only* one subject with a clear title
+      and description in grammatically correct, complete sentences
 * [ ] I think the code is well written
-* [ ] I wrote [good commit messages]
-* [ ] I have [squashed related commits together][related squash] after
-      the changes have been approved
 * [ ] Unit tests for the changes exist
 * [ ] Integration tests for the changes exist (if applicable)
 * [ ] I used the same coding conventions as the rest of the project
 * [ ] The new code doesn't generate linter offenses
-* [ ] Documentation reflects the changes
-* [ ] The PR relates to *only* one subject with a clear title
-      and description in grammatically correct, complete sentences
-
+* [ ] Project documentation (in `docs/`) and inline docstrings reflect the changes
+* [ ] My commits each have a descriptive title and a body explaining the why
+      (see [guide][good commit messages])
+* [ ] I have added a [changelog][changelog-fragments] entry
+      (can be done once the PR number is known)
+* [ ] I'm planning to [squash related commits together][related squash]
+      before final merge
+* [ ] I have read the [contribution guide][CONTRIBUTING] and the
+      [code of conduct][CoC]
+
+[CONTRIBUTING]: https://cheroot.cherrypy.dev/en/latest/contributing/guidelines/
+[CoC]: https://github.com/cherrypy/cheroot?tab=coc-ov-file#readme
+[changelog-fragments]:
+https://github.com/cherrypy/cheroot/tree/main/docs/changelog-fragments.d#readme
 [good commit messages]: http://chris.beams.io/posts/git-commit/
 [making a lovely PR]: https://mtlynch.io/code-review-love/
 [related squash]:
diff --git a/docs/changelog-fragments.d/834.contrib.rst b/docs/changelog-fragments.d/834.contrib.rst
new file mode 100644
index 0000000000..43db925f0d
--- /dev/null
+++ b/docs/changelog-fragments.d/834.contrib.rst
@@ -0,0 +1,4 @@
+Updated the pull request template with consistent heading structure,
+a change log entry checkbox linking to the change log guidelines,
+and improved commit message guidance
+-- by :user:`julianz-`.