DOCS: pr template grammar and visual organization

brunobeltran · brunobeltran · commit 80c449648f09 · 2020-04-27T18:24:49.000-07:00
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,24 +1,36 @@
 ## PR Summary
 
 <!--
-Please provide at least a 1-2 sentence summary of the purpose of the PR.
+Thank you so much for your PR! Please summarize the purpose of the PR here
+using at least 1-2 sentences.
+
+To help us review your pull request, make sure:
+
+- The PR title descriptively summarizes the changes.
+    - e.g. "Raise `ValueError` on non-numeric input to `set_xlim`"
+    - Please don't use non-descriptive titles such as "Addresses issue #8576".
+- The PR summary includes:
+    - How the PR implements any changes.
+    - Why these changes are necessary.
+- The PR is not out of master, but out of a separate branch.
+    - e.g. `your-user-name:non-numeric-xlim -> matplotlib:master`
+- Optional: PR cross-links related issues.
 -->
 
-
 ## PR Checklists
 
 <!-- Feel free to delete any checkboxes that do not apply to this PR. -->
 
 New code:
 
-- [ ] Has Pytest style unit tests (and `pytest lib/matplotlib/tests` passes)
-- [ ] Code is [Flake 8](http://flake8.pycqa.org/en/latest/) compliant (run `flake8` on changed files to check)
-- [ ] Code is documented, with examples if plot related
+- [ ] has Pytest style unit tests (and `pytest lib/matplotlib/tests` passes)
+- [ ] is [Flake 8](http://flake8.pycqa.org/en/latest/) compliant (run `flake8` on changed files to check)
+- [ ] is documented, with examples if plot related
 
 New documentation:
 
-- [ ] Documentation is sphinx and numpydoc compliant (the docs should [build](https://matplotlib.org/devel/documenting_mpl.html#building-the-docs) without error)
-- [ ] Documentation conforms to matplotlib style conventions. (If you have `flake8-docstrings` and `pydocstyle<4` installed, run `flake8 --docstring-convention=all` on changed files to check).
+- [ ] is sphinx and numpydoc compliant (the docs should [build](https://matplotlib.org/devel/documenting_mpl.html#building-the-docs) without error)
+- [ ] conforms to matplotlib style conventions (if you have `flake8-docstrings` and `pydocstyle<4` installed, run `flake8 --docstring-convention=all` on changed files to check).
 <!--
 - If you are contributing fixes to docstrings, please pay attention to
   http://matplotlib.org/devel/documenting_mpl.html#formatting. In particular,
@@ -28,20 +40,11 @@ New documentation:
 
 New features:
 
-- [ ] Have an entry in `doc/users/next_whats_new/` (follow instructions in `doc/users/next_whats_new/README.rst`)
+- [ ] have an entry in `doc/users/next_whats_new/` (follow instructions in `doc/users/next_whats_new/README.rst`)
 
 API changes:
 
-- [ ] Documented in `doc/api/api_changes_[NEXT_VERSION]` if API changed in a backward-incompatible way (follow instructions in `doc/api/api_changes_[NEXT_VERSION]/README.rst`)
-
-<!--
-Meta:
-
-- PR title descriptively summarizes the changes. (For example, prefer "Raise `ValueError` on non-numeric input to `set_xlim`" to "Addresses issue #8576").
-- PR has at least a 1-2 sentence summary.
-- PR is not out of master, but out of a separate branch (e.g. `your-user-name:non-numeric-xlim -> matplotlib:master`)
-- Optional: PR cross-links related issues.
--->
+- [ ] are documented in `doc/api/api_changes_[NEXT_VERSION]` if API changed in a backward-incompatible way (follow instructions in `doc/api/api_changes_[NEXT_VERSION]/README.rst`)
 
 <!--
 If you have further questions:
@@ -53,7 +56,7 @@ If you have further questions:
   https://matplotlib.org/devel/gitwash/development_workflow.html.
 
 We understand that PRs can sometimes be overwhelming, especially as the
-reviews start coming in. Please let us know if the reviews are unclear,  
+reviews start coming in. Please let us know if the reviews are unclear,
 the recommended next step seems overly demanding, you would like help in
 addressing a reviewer's comments, or you have been waiting too long to hear
 back on your PR.
