matplotlib · tacaswell · Dec 5, 2022 · Aug 2, 2022 · Aug 28, 2022 · Aug 29, 2022
diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst
@@ -13,8 +13,92 @@
 Pull request guidelines
 ***********************
 
-Pull requests (PRs) are the mechanism for contributing to Matplotlibs code and
-documentation.
+`Pull requests (PRs) on GitHub
+<https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`__
+are the mechanism for contributing to Matplotlib's code and documentation.
+
+It is recommended to check that your contribution complies with the following
+rules before submitting a pull request:
+
+* If your pull request addresses an issue, please use the title to describe the
+  issue (e.g. "Add ability to plot timedeltas") and mention the issue number
+  in the pull request description to ensure that a link is created to the
+  original issue (e.g. "Closes #8869" or "Fixes #8869"). This will ensure the
+  original issue mentioned is automatically closed when your PR is merged. See
+  `the GitHub documentation
+  <https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue>`__
+  for more details.
+
+* Formatting should follow the recommendations of PEP8_, as enforced by
+  flake8_.  You can check flake8 compliance from the command line with ::
+
+    python -m pip install flake8
+    flake8 /path/to/module.py
+
+  or your editor may provide integration with it.  Note that Matplotlib
+  intentionally does not use the black_ auto-formatter (1__), in particular due
+  to its unability to understand the semantics of mathematical expressions
+  (2__, 3__).
+
+  .. _PEP8: https://www.python.org/dev/peps/pep-0008/
+  .. _flake8: https://flake8.pycqa.org/
+  .. _black: https://black.readthedocs.io/
+  .. __: https://github.com/matplotlib/matplotlib/issues/18796
+  .. __: https://github.com/psf/black/issues/148
+  .. __: https://github.com/psf/black/issues/1984
+
+* All public methods should have informative docstrings with sample usage when
+  appropriate. Use the :ref:`docstring standards <writing-docstrings>`.
+
+* For high-level plotting functions, consider adding a simple example either in
+  the ``Example`` section of the docstring or the
+  :ref:`examples gallery <gallery>`.
+
+* Changes (both new features and bugfixes) should have good test coverage. See
+  :ref:`testing` for more details.
+
+* Import the following modules using the standard scipy conventions::
+
+     import numpy as np
+     import numpy.ma as ma
+     import matplotlib as mpl
+     import matplotlib.pyplot as plt
+     import matplotlib.cbook as cbook
+     import matplotlib.patches as mpatches
+
+  In general, Matplotlib modules should **not** import `.rcParams` using ``from
+  matplotlib import rcParams``, but rather access it as ``mpl.rcParams``.  This
+  is because some modules are imported very early, before the `.rcParams`
+  singleton is constructed.
+
+* If your change is a major new feature, add an entry to the ``What's new``
+  section by adding a new file in ``doc/users/next_whats_new`` (see
+  :file:`doc/users/next_whats_new/README.rst` for more information).
+
+* If you change the API in a backward-incompatible way, please document it in
+  :file:`doc/api/next_api_changes/behavior`, by adding a new file with the
+  naming convention ``99999-ABC.rst`` where the pull request number is followed
+  by the contributor's initials. (see :file:`doc/api/api_changes.rst` for more
+  information)
+
+* See below for additional points about :ref:`keyword-argument-processing`, if
+  applicable for your pull request.
+
+.. note::
+
+    The current state of the Matplotlib code base is not compliant with all
+    of these guidelines, but we expect that enforcing these constraints on all
+    new contributions will move the overall code base quality in the right
+    direction.
+
+
+.. seealso::
+
+  * :ref:`coding_guidelines`
+  * :ref:`testing`
+  * :ref:`documenting-matplotlib`
+
+
 
 Summary for pull request authors
 ================================

diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst
@@ -4,13 +4,20 @@
 Contributing
 ============
 
+You've discovered a bug or something else you want to change
+in Matplotlib — excellent!
+
+You've worked out a way to fix it — even better!
+
+You want to tell us about it — best of all!
+
 This project is a community effort, and everyone is welcome to
 contribute. Everyone within the community
 is expected to abide by our
 `code of conduct <https://github.com/matplotlib/matplotlib/blob/main/CODE_OF_CONDUCT.md>`_.
 
-The project is hosted on
-https://github.com/matplotlib/matplotlib
+Below, you can find a number of ways to contribute, and how to connect with the
+Matplotlib community.
 
 Get Connected
 =============
@@ -192,96 +199,8 @@ A brief overview is:
 Finally, go to the web page of your fork of the Matplotlib repo, and click
 'Pull request' to send your changes to the maintainers for review.
 
-.. seealso::
-
-  * `Git documentation <https://git-scm.com/doc>`_
-  * `Git-Contributing to a Project <https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project>`_
-  * `Introduction to GitHub  <https://lab.github.com/githubtraining/introduction-to-github>`_
-  * :ref:`development-workflow` for best practices for Matplotlib
-  * :ref:`using-git`
-
-Contributing pull requests
---------------------------
-
-It is recommended to check that your contribution complies with the following
-rules before submitting a pull request:
-
-* If your pull request addresses an issue, please use the title to describe the
-  issue and mention the issue number in the pull request description to ensure
-  that a link is created to the original issue.
-
-* All public methods should have informative docstrings with sample usage when
-  appropriate. Use the `numpy docstring standard
-  <https://numpydoc.readthedocs.io/en/latest/format.html>`_.
-
-* Formatting should follow the recommendations of PEP8_, as enforced by
-  flake8_.  You can check flake8 compliance from the command line with ::
-
-    python -m pip install flake8
-    flake8 /path/to/module.py
-
-  or your editor may provide integration with it.  Note that Matplotlib
-  intentionally does not use the black_ auto-formatter (1__), in particular due
-  to its inability to understand the semantics of mathematical expressions
-  (2__, 3__).
-
-  .. _PEP8: https://www.python.org/dev/peps/pep-0008/
-  .. _flake8: https://flake8.pycqa.org/
-  .. _black: https://black.readthedocs.io/
-  .. __: https://github.com/matplotlib/matplotlib/issues/18796
-  .. __: https://github.com/psf/black/issues/148
-  .. __: https://github.com/psf/black/issues/1984
-
-* Each high-level plotting function should have a simple example in the
-  ``Example`` section of the docstring.  This should be as simple as possible
-  to demonstrate the method.  More complex examples should go in the
-  ``examples`` tree.
-
-* Changes (both new features and bugfixes) should have good test coverage. See
-  :ref:`testing` for more details.
-
-* Import the following modules using the standard scipy conventions::
-
-     import numpy as np
-     import numpy.ma as ma
-     import matplotlib as mpl
-     import matplotlib.pyplot as plt
-     import matplotlib.cbook as cbook
-     import matplotlib.patches as mpatches
-
-  In general, Matplotlib modules should **not** import `.rcParams` using ``from
-  matplotlib import rcParams``, but rather access it as ``mpl.rcParams``.  This
-  is because some modules are imported very early, before the `.rcParams`
-  singleton is constructed.
-
-* If your change is a major new feature, add an entry to the ``What's new``
-  section by adding a new file in ``doc/users/next_whats_new`` (see
-  :file:`doc/users/next_whats_new/README.rst` for more information).
-
-* If you change the API in a backward-incompatible way, please document it in
-  :file:`doc/api/next_api_changes/behavior`, by adding a new file with the
-  naming convention ``99999-ABC.rst`` where the pull request number is followed
-  by the contributor's initials. (see :file:`doc/api/api_changes.rst` for more
-  information)
-
-* See below for additional points about :ref:`keyword-argument-processing`, if
-  applicable for your pull request.
-
-.. note::
-
-    The current state of the Matplotlib code base is not compliant with all
-    of those guidelines, but we expect that enforcing those constraints on all
-    new contributions will move the overall code base quality in the right
-    direction.
-
-
-.. seealso::
-
-  * :ref:`coding_guidelines`
-  * :ref:`testing`
-  * :ref:`documenting-matplotlib`
-
-
+For more detailed instructions on how to set up Matplotlib for development and
+best practices for contribution, see :ref:`installing_for_devs`.
 
 
 .. _contributing_documentation:

diff --git a/doc/devel/development_setup.rst b/doc/devel/development_setup.rst
@@ -9,38 +9,63 @@ To set up Matplotlib for development follow these steps:
 .. contents::
    :local:
 
+Fork the Matplotlib repository
+==============================
+
+Matplotlib is hosted at https://github.com/matplotlib/matplotlib.git. If you
+plan on solving issues or submit pull requests to the main Matplotlib
+repository, you should first *fork* this repository by visiting
+https://github.com/matplotlib/matplotlib.git and clicking on the
+``Fork`` button on the top right of the page (see
+`the GitHub documentation <https://docs.github.com/get-started/quickstart/fork-a-repo>`__ for more details.)
+
 Retrieve the latest version of the code
 =======================================
 
-Matplotlib is hosted at https://github.com/matplotlib/matplotlib.git.
-
-You can retrieve the latest sources with the command (see
-:ref:`set-up-fork` for more details)
+Now that your fork of the repository lives under your GitHub username, you can
+retrieve the latest sources with one of the following commands (where your
+should replace ``<your-username>`` with your GitHub username):
 
 .. tab-set::
 
    .. tab-item:: https
 
       .. code-block:: bash
 
-         git clone https://github.com/matplotlib/matplotlib.git
+         git clone https://github.com/<your-username>/matplotlib.git
 
    .. tab-item:: ssh
 
       .. code-block:: bash
 
-         git clone git@github.com:matplotlib/matplotlib.git
+         git clone git@github.com:<your-username>/matplotlib.git
 
       This requires you to setup an `SSH key`_ in advance, but saves you from
       typing your password at every connection.
 
       .. _SSH key: https://docs.github.com/en/authentication/connecting-to-github-with-ssh
 
+
 This will place the sources in a directory :file:`matplotlib` below your
-current working directory. Change into this directory::
+current working directory, set up the ``origin`` remote to point to your own
+fork, and set up the ``upstream`` remote to point to the Matplotlib main
+repository (see also `Managing remote repositories <https://docs.github.com/en/get-started/getting-started-with-git/managing-remote-repositories>`__.)
+Change into this directory before continuing::
 
     cd matplotlib
 
+.. note::
+
+  For more information on ``git`` and ``GitHub``, check the following resources.
+
+  * `Git documentation <https://git-scm.com/doc>`_
+  * `GitHub-Contributing to a Project <https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project>`_
+  * `Introduction to GitHub <https://lab.github.com/githubtraining/introduction-to-github>`_
+  * :ref:`using-git`
+  * :ref:`git-resources`
+  * `Installing git <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_
+  * https://tacaswell.github.io/think-like-git.html
+  * https://tom.preston-werner.com/2009/05/19/the-git-parable.html
 
 .. _dev-environment:
 
@@ -86,12 +111,8 @@ The simplest way to do this is to use either Python's virtual environment
 
 Remember to activate the environment whenever you start working on Matplotlib.
 
-Install additional development dependencies
-===========================================
-See :ref:`development-dependencies`.
-
-Install Matplotlib in editable mode
-===================================
+Installing Matplotlib in editable mode
+======================================
 Install Matplotlib in editable mode from the :file:`matplotlib` directory
 using the command ::
 
@@ -105,6 +126,10 @@ true for ``*.py`` files.  If you change the C-extension source (which might
 also happen if you change branches) you will have to re-run
 ``python -m pip install -ve .``
 
+Install additional development dependencies
+===========================================
+See :ref:`development-dependencies`.
+
 Install pre-commit hooks (optional)
 ===================================
 `pre-commit <https://pre-commit.com/>`_ hooks automatically check flake8 and