DOC: verify your changes

rcomer · rcomer · commit 9236c53db7e3 · 2024-11-26T19:08:40.000Z
diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst
@@ -340,13 +340,15 @@ then submit a "pull request" (PR). To work on a a pull request:
    Matplotlib repository to your own computer or by using Github codespaces, by
    following the instructions in :ref:`installing_for_devs`
 
-#. **Then** start a pull request by following the guidance in :ref:`development workflow <development-workflow>`
+#. **Then** start solving the issue, following the guidance in
+   :ref:`development workflow <development-workflow>`
 
-#. **After starting** check that your contribution meets the :ref:`pull request guidelines <pr-author-guidelines>`
-   and :ref:`update the pull request <update-pull-request>` as needed.
+#. **As part of verifying your changes** check that your contribution meets
+   the :ref:`pull request guidelines <pr-author-guidelines>`
+   and then :ref:`open a pull request <open-pull-request>`.
 
 #. **Finally** follow up with maintainers on the PR if waiting more than a few days for
-   feedback.
+   feedback.  :ref:`Update the pull request <update-pull-request>` as needed.
 
 If you have questions of any sort, reach out on the :ref:`contributor_incubator` and join
 the :ref:`new_contributors_meeting`.
diff --git a/doc/devel/development_workflow.rst b/doc/devel/development_workflow.rst
@@ -146,6 +146,27 @@ The editing workflow
 .. _why the -a flag?: http://gitready.com/beginner/2009/01/18/the-staging-area.html
 
 
+Verify your changes
+===================
+
+Check that your change does what you intend.  For code changes:
+
+* If the issue you are working on provided a code example, run that example
+  against your branch and check that you now get the desired result.  Note that
+  adapting the issue example is often a good way to create a new test.
+
+* Run the tests to check that your change has not had unintended consequences
+  on existing functionality.  See :ref:`run_tests`.
+
+For documentation changes, build the documentation locally to check that
+it renders how you intended and that any new links work correctly.  See
+:ref:`build_docs`.
+
+This is also a good time to look through the :ref:`pr-author-guidelines` and
+address as many of the relevant points as you can.
+
+.. _open-pull-request:
+
 Open a pull request
 ===================
 
diff --git a/doc/devel/document.rst b/doc/devel/document.rst
@@ -52,6 +52,8 @@ To build the documentation you will need to
 particular the :ref:`additional dependencies <doc-dependencies>` required to
 build the documentation.
 
+.. _build_docs:
+
 Build the docs
 --------------
 
diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst
@@ -32,6 +32,8 @@ particular the :ref:`additional dependencies <test-dependencies>` for testing.
    You have to additionally get the reference images from the repository,
    because they are not distributed with pre-built Matplotlib packages.
 
+.. _run_tests:
+
 Running the tests
 -----------------
 
