From e41cd71c2383d6ee9a1e549d540dd7d5286f9128 Mon Sep 17 00:00:00 2001
From: Sam Evans <47793072+Sevans711@users.noreply.github.com>
Date: Mon, 24 Aug 2026 11:40:36 -0400
Subject: [PATCH 1/2] make PR template form more concise and clear

---
 .github/PULL_REQUEST_TEMPLATE.md | 64 ++++++++++++++------------------
 1 file changed, 28 insertions(+), 36 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index ea8d62327..1d4d66bd9 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,15 +1,22 @@
-<!--  The PR title should summarize the changes, for example "Add `Grid._build_face_dimension` function".
+<!--  Thank you for opening a PR! To help us review your contribution, please follow instructions below
+      while filling out this form, and read the etiquette reminders at the bottom. -->
+
+<!--  Please ensure the PR title summarizes the changes, e.g. "Adds `Grid._build_face_dimension` function".
       Avoid non-descriptive titles such as "Addresses issue #229". -->
 
+Closes #XXX
 <!--  Replace XXX with the issue number resolved by this PR, if this PR fully resolves an issue.
+      If it resolves multiple issues, repeat "closes" for each, like "Closes #XXX, closes #YYY."
       If it does not fully resolve any issues, replace with something like "Related to #XXX",
-          or "Fixes part of #YYY but does not fully close it."
-      If it resolves multiple issues, repeat "closes" for each, like "Closes #XXX, closes #YYY." -->
-Closes #XXX
+          or "Fixes part of #YYY but does not fully close it." -->
 
 ## Overview
-<!--  Please provide a few bullet points summarizing the changes in this PR. This should include
-      points on any bug fixes, new functions, or other changes that have been made. -->
+<!--  Please summarize the changes in this PR. How does it solve the original issue? -->
+
+
+<!--  Does the scope of this PR do anything aside from just solving the original issue?
+      And/or, does it not fully solve the issue as originally reported? If so, please clarify. -->
+
 
 ## Expected Usage
 <!--  If this PR adds a new feature, please provide a short example of it in action.
@@ -30,7 +37,7 @@ other_output = uxds.some_function(some_param = True)
 ```
 
 ## PR Checklist
-<!-- Please mark any checkboxes that do not apply to this PR as [N/A]. -->
+<!-- Please mark each item as [X] when completed, or [N/A] if not applicable to this PR. -->
 
 **General**
 - [ ] An issue is created and linked
@@ -38,28 +45,21 @@ other_output = uxds.some_function(some_param = True)
 - [ ] Filled out Overview and Expected Usage (if applicable) sections
 
 **Testing & Benchmarking**
-<!--  If this PR does not update any functionality or tests and is unlikely to affect efficiency,
-    e.g. by affecting computation time or memory usage, remove this section (Testing & Benchmarking) -->
-- [ ] Adequate tests are created if there is new functionality
-- [ ] Tests are not too basic (such as simply calling a function and nothing else)
-- [ ] Tests cover all major paths in your new functions
+- [ ] There is adequate test coverage of changes from this PR (add new tests if needed)
 - [ ] If this PR could affect performance, ran ASV benchmarks and confirmed they show expected behavior (add a new benchmark if necessary)
 <!-- Adding the run-benchmark label (if your uxarray repo permissions allow it) will run ASV benchmarks.
     If you need benchmarks to be run but don't have permissions, leave this item unchecked for now. -->
 
 **Documentation**
-<!--  If this PR does not update any functionality or docstrings, remove this section (Documentation) -->
-- [ ] Docstrings have been added to all new functions
-- [ ] Docstrings have been updated with any function changes
-- [ ] User (public) functions have been added to `docs/api.rst`
-- [ ] Internal (private) function names start with an underscore (`_`)
+- [ ] Docstrings updated with any function changes, and included in all new functions
+- [ ] User (public) functions added to `docs/api.rst`; internal (private) function names start with an underscore (`_`)
 
 **Examples**
-<!--  If this PR does not affect any example notebooks, remove this section (Examples) -->
-- [ ] **All** notebook examples cleared the output of all cells before committing
-- [ ] New notebook examples added to appropriate folder (gallery: `docs/examples/`; guide: `docs/user-guide/`; quickstart: `docs/getting-started/`)
-- [ ] New notebook examples referenced in appropriate .rst file (gallery: `docs/gallery.rst`; guide: `docs/userguide.rst`; quickstart: `docs/quickstart.rst`)
-- [ ] New notebook gallery examples added entry in `docs/gallery.yml` with appropriate thumbnail photo in `docs/_static/thumbnails/`
+- [ ] If touched any notebook examples, cleared the output of all cells before committing
+- [ ] If added new notebook examples, put in appropriate folder(s) and referenced in appropriate docs files
+<!-- Appropriate folders for reference: (gallery: `docs/examples/`; guide: `docs/user-guide/`; quickstart: `docs/getting-started/`)
+    Appropriate .rst files for reference: (gallery: `docs/gallery.rst`; guide: `docs/userguide.rst`; quickstart: `docs/quickstart.rst`)
+    For gallery examples also add reference in `docs/gallery.yml` and thumbnail photo in `docs/_static/thumbnails/`-->
 
 
 ## AI Disclosure
@@ -71,19 +71,11 @@ other_output = uxds.some_function(some_param = True)
 
 AI Usage:
 
-- [ ] I take responsibility for all AI-generated content in my PR.
-- [ ] I have tested all AI-generated content in my PR.
-
-<!--
-Thank you so much for your PR!  To help us review your contribution, please
-consider the following points:
-
-**PR Etiquette Reminders**
-- This PR should be listed as a draft PR until you are ready for it to be reviewed
-
-- After making changes in accordance with any reviews, re-request reviews from the same reviewers
-
-- Do *not* mark conversations as resolved if you didn't start them
+- [ ] I have tested and take responsibility for all AI-generated content in my PR.
 
-- Do mark conversations as resolved *if you opened them* and are satisfied with the changes/discussion.
+<!-- **PR Etiquette Reminders**
+- Please list as "draft PR" until ready for review.
+- Please do NOT mark any review comment threads as resolved.
+- Instead, please notify reviewers after addressing their comments, via @username or the "re-request review" button.
+- (Reviewers: please mark your own threads as resolved after confirming your comments have been addressed.)
 -->

From 76793f53ea944240b5347c91b4aaa81c58bede1b Mon Sep 17 00:00:00 2001
From: Sam Evans <47793072+Sevans711@users.noreply.github.com>
Date: Wed, 26 Aug 2026 15:01:52 -0400
Subject: [PATCH 2/2] put example notebook details in contributors guide

and remove those details from pr template form. pr template form now links to the relevant part of that docs page instead of providing all details inline.

Also, merges Documentation with Examples section in pr checklist, and edits examples language slightly.
---
 .github/PULL_REQUEST_TEMPLATE.md | 14 +++++---------
 docs/contributing.rst            | 21 +++++++++++++++++----
 2 files changed, 22 insertions(+), 13 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 1d4d66bd9..9a9d8f913 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -50,17 +50,13 @@ other_output = uxds.some_function(some_param = True)
 <!-- Adding the run-benchmark label (if your uxarray repo permissions allow it) will run ASV benchmarks.
     If you need benchmarks to be run but don't have permissions, leave this item unchecked for now. -->
 
-**Documentation**
+**Documentation and Examples**
 - [ ] Docstrings updated with any function changes, and included in all new functions
 - [ ] User (public) functions added to `docs/api.rst`; internal (private) function names start with an underscore (`_`)
-
-**Examples**
-- [ ] If touched any notebook examples, cleared the output of all cells before committing
-- [ ] If added new notebook examples, put in appropriate folder(s) and referenced in appropriate docs files
-<!-- Appropriate folders for reference: (gallery: `docs/examples/`; guide: `docs/user-guide/`; quickstart: `docs/getting-started/`)
-    Appropriate .rst files for reference: (gallery: `docs/gallery.rst`; guide: `docs/userguide.rst`; quickstart: `docs/quickstart.rst`)
-    For gallery examples also add reference in `docs/gallery.yml` and thumbnail photo in `docs/_static/thumbnails/`-->
-
+- [ ] If touched any notebook files, cleared the output of all cells before committing
+- [ ] If added new notebook files, put into appropriate directories and referenced in appropriate files
+<!-- For appropriate directories/files for notebooks, see
+    https://uxarray.readthedocs.io/en/latest/contributing.html#usage-examples -->
 
 ## AI Disclosure
 <!-- Please specify all AI tools used. Optionally, include model and/or briefly describe usage. Examples:
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 3e2570cbc..cffde8e8f 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -623,10 +623,23 @@ file so that its documentation page is automatically generated.
     needed. However, it would be a great practice to provide usage examples in the
     same PR, especially for demonstrating the use of complex UXarray functions.
 
-The UXarray documentation houses ``docs/examples/<example-name>.ipynb`` files (paths
-relative from the root directory) to provide `Usage Examples <gallery.rst>`_ to be
-automatically generated. If you prefer to provide usage examples for the work you
-have put together, please be sure to put your notebook(s) under this same directory.
+The UXarray documentation pages are built from a combination of ``.rst`` and ``.ipynb`` files.
+Jupyter notebook files should be cleared of all outputs before committing, and will be run and
+linked in the docs automatically when when the docs pages are built, as long as there is
+at least one reference to them in the appropriate ``.rst`` file(s).
+
+To add a usage example to the `Gallery <gallery.rst>`_, be sure to
+put the notebook file into the ``docs/examples/`` directory,
+add a reference to it in both the ``docs/gallery.rst`` and ``docs/gallery.yml`` files,
+and add a thumbnail photo into ``docs/_static/thumbnails/``.
+
+To add a page to the `User Guide <userguide.rst>`_, be sure to
+put the notebook file into the ``docs/user-guide/`` directory,
+and add a reference to it in the ``docs/userguide.rst`` file.
+
+To add a page to the `Getting Started / Quick Start Guide <quickstart.rst>`_, be sure to
+put the notebook file into the ``docs/getting-started/`` directory,
+and add a reference to it in the ``docs/quickstart.rst`` file.
 
 3.7.4. After You Open The Pull Request
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^