Merge pull request matplotlib#29048 from story645/contrib-shuffle

DOC: integrated pr workflow from contributing guide into install and workflow

Author: timhoffm

doc/devel/contribute.rst

@@ -319,113 +319,19 @@ Start a pull request
 
 The preferred way to contribute to Matplotlib is to fork the `main
 repository <https://github.com/matplotlib/matplotlib/>`__ on GitHub,
-then submit a "pull request" (PR). You can do this by cloning a copy of the
-Matplotlib repository to your own computer, or alternatively using
-`GitHub Codespaces <https://docs.github.com/codespaces>`_, a cloud-based
-in-browser development environment that comes with the appropriate setup to
-contribute to Matplotlib.
+then submit a "pull request" (PR). To work on a a pull request:
 
-Workflow overview
------------------
-
-A brief overview of the workflow is as follows.
-
-#. `Create an account <https://github.com/join>`_ on GitHub if you do not
-   already have one.
-
-#. Fork the `project repository <https://github.com/matplotlib/matplotlib>`_ by
-   clicking on the :octicon:`repo-forked` **Fork** button near the top of the page.
-   This creates a copy of the code under your account on the GitHub server.
-
-#. Set up a development environment:
-
-   .. tab-set::
-
-      .. tab-item:: Local development
-
-          Clone this copy to your local disk::
-
-            git clone https://github.com/<YOUR GITHUB USERNAME>/matplotlib.git
-
-      .. tab-item:: Using GitHub Codespaces
-
-          Check out the Matplotlib repository and activate your development environment:
-
-          #. Open codespaces on your fork by clicking on the green "Code" button
-             on the GitHub web interface and selecting the "Codespaces" tab.
-
-          #. Next, click on "Open codespaces on <your branch name>". You will be
-             able to change branches later, so you can select the default
-             ``main`` branch.
-
-          #. After the codespace is created, you will be taken to a new browser
-             tab where you can use the terminal to activate a pre-defined conda
-             environment called ``mpl-dev``::
-
-              conda activate mpl-dev
-
-
-#. Install the local version of Matplotlib with::
-
-     python -m pip install --no-build-isolation --editable .[dev]
-
-   See :ref:`installing_for_devs` for detailed instructions.
-
-#. Create a branch to hold your changes::
-
-     git checkout -b my-feature origin/main
-
-   and start making changes. Never work in the ``main`` branch!
-
-#. Work on this task using Git to do the version control. Codespaces persist for
-   some time (check the `documentation for details
-   <https://docs.github.com/codespaces/getting-started/the-codespace-lifecycle>`_)
-   and can be managed on https://github.com/codespaces. When you're done editing
-   e.g., ``lib/matplotlib/collections.py``, do::
-
-     git add lib/matplotlib/collections.py
-     git commit -m 'a commit message'
-
-   to record your changes in Git, then push them to your GitHub fork with::
-
-     git push -u origin my-feature
-
-GitHub Codespaces workflows
-"""""""""""""""""""""""""""
-
-If you need to open a GUI window with Matplotlib output on Codespaces, our
-configuration includes a `light-weight Fluxbox-based desktop
-<https://github.com/devcontainers/features/tree/main/src/desktop-lite>`_.
-You can use it by connecting to this desktop via your web browser. To do this:
-
-#. Press ``F1`` or ``Ctrl/Cmd+Shift+P`` and select
-    ``Ports: Focus on Ports View`` in the VSCode session to bring it into
-    focus. Open the ports view in your tool, select the ``noVNC`` port, and
-    click the Globe icon.
-#. In the browser that appears, click the Connect button and enter the desktop
-    password (``vscode`` by default).
-
-Check the `GitHub instructions
-<https://github.com/devcontainers/features/tree/main/src/desktop-lite#connecting-to-the-desktop>`_
-for more details on connecting to the desktop.
-
-View documentation
-''''''''''''''''''
+#. **First** set up a development environment, either by cloning a copy of the
+   Matplotlib repository to your own computer or by using Github codespaces, by
+   following the instructions in :ref:`installing_for_devs`
 
-If you also built the documentation pages, you can view them using Codespaces.
-Use the "Extensions" icon in the activity bar to install the "Live Server"
-extension. Locate the ``doc/build/html`` folder in the Explorer, right click
-the file you want to open and select "Open with Live Server."
+#. **Then** start a pull request by following the guidance in :ref:`development workflow <development-workflow>`
 
-Open a pull request on Matplotlib
----------------------------------
+#. **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.
 
-Finally, go to the web page of *your fork* of the Matplotlib repo, and click
-**Compare & pull request** to send your changes to the maintainers for review.
-The base repository is ``matplotlib/matplotlib`` and the base branch is
-generally ``main``. For more guidance, see GitHub's `pull request tutorial
-<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_.
+#. **Finally** follow up with maintainers on the PR if waiting more than a few days for
+   feedback.
 
-For more detailed instructions on how to set up Matplotlib for development and
-best practices for contribution, see :ref:`installing_for_devs` and
-:ref:`development-workflow`.
+If you have questions of any sort, reach out on the :ref:`contributor_incubator` and join
+the :ref:`new_contributors_meeting`.

doc/devel/development_setup.rst

@@ -28,11 +28,11 @@ Fork the Matplotlib repository
 
 Matplotlib is hosted at https://github.com/matplotlib/matplotlib.git. If you
 plan on solving issues or submitting 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`` :octicon:`repo-forked` 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.
+repository, you should first fork this repository by *clicking* the
+:octicon:`repo-forked` **Fork** button near the top of the `project repository <https://github.com/matplotlib/matplotlib>`_ page.
+
+This creates a copy of the code under your account on the GitHub server. See `the GitHub
+documentation <https://docs.github.com/get-started/quickstart/fork-a-repo>`__ for more details.
 
 Retrieve the latest version of the code
 =======================================
@@ -111,8 +111,9 @@ Create a dedicated environment
 You should set up a dedicated environment to decouple your Matplotlib
 development from other Python and Matplotlib installations on your system.
 
-The simplest way to do this is to use either Python's virtual environment
-`venv`_ or `conda`_.
+We recommend using one of the following options for a dedicated development environment
+because these options are configured to install the Python dependencies as part of their
+setup.
 
 .. _venv: https://docs.python.org/3/library/venv.html
 .. _conda: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html
@@ -138,6 +139,8 @@ The simplest way to do this is to use either Python's virtual environment
 
         pip install -r requirements/dev/dev-requirements.txt
 
+      Remember to activate the environment whenever you start working on Matplotlib!
+
    .. tab-item:: conda environment
 
       Create a new `conda`_ environment and install the Python dependencies with ::
@@ -153,21 +156,66 @@ The simplest way to do this is to use either Python's virtual environment
 
         conda activate mpl-dev
 
-Remember to activate the environment whenever you start working on Matplotlib.
+      Remember to activate the environment whenever you start working on Matplotlib!
+
+   .. tab-item:: :octicon:`codespaces` GitHub Codespaces
+
+      `GitHub Codespaces <https://docs.github.com/codespaces>`_ is a cloud-based
+      in-browser development environment that comes with the appropriate setup to
+      contribute to Matplotlib.
+
+      #. Open codespaces on your fork by clicking on the green :octicon:`code` ``Code``
+         button on the GitHub web interface and selecting the ``Codespaces`` tab.
+
+      #. Next, click on "Open codespaces on <your branch name>". You will be
+         able to change branches later, so you can select the default
+         ``main`` branch.
+
+      #. After the codespace is created, you will be taken to a new browser
+         tab where you can use the terminal to activate a pre-defined conda
+         environment called ``mpl-dev``::
+
+         conda activate mpl-dev
+
+      Remember to activate the *mpl-dev* environment whenever you start working on
+      Matplotlib.
+
+      If you need to open a GUI window with Matplotlib output on Codespaces, our
+      configuration includes a `light-weight Fluxbox-based desktop
+      <https://github.com/devcontainers/features/tree/main/src/desktop-lite>`_.
+      You can use it by connecting to this desktop via your web browser. To do this:
+
+      #. Press ``F1`` or ``Ctrl/Cmd+Shift+P`` and select
+         ``Ports: Focus on Ports View`` in the VSCode session to bring it into
+         focus. Open the ports view in your tool, select the ``noVNC`` port, and
+         click the Globe icon.
+      #. In the browser that appears, click the Connect button and enter the desktop
+         password (``vscode`` by default).
+
+      Check the `GitHub instructions
+      <https://github.com/devcontainers/features/tree/main/src/desktop-lite#connecting-to-the-desktop>`_
+      for more details on connecting to the desktop.
+
+      If you also built the documentation pages, you can view them using Codespaces.
+      Use the "Extensions" icon in the activity bar to install the "Live Server"
+      extension. Locate the ``doc/build/html`` folder in the Explorer, right click
+      the file you want to open and select "Open with Live Server."
+
 
 Install external dependencies
 =============================
 
 Python dependencies were installed as part of :ref:`setting up the environment <dev-environment>`.
-Additionally, the following non-Python dependencies must also be installed:
+Additionally, the following non-Python dependencies must also be installed locally:
 
 .. rst-class:: checklist
 
 * :ref:`c++ compiler<compile-dependencies>`
 * :ref:`documentation build dependencies <doc-dependencies-external>`
 
 
-For a full list of dependencies, see :ref:`dependencies`.
+For a full list of dependencies, see :ref:`dependencies`. External dependencies do not
+need to be installed when working in codespaces.
 
 .. _development-install:
 

doc/devel/development_workflow.rst

@@ -28,6 +28,30 @@ why you did it, we recommend the following:
   Matplotlib developers can give feedback and eventually include your suggested
   code into the ``main`` branch.
 
+Overview
+--------
+
+After :ref:`setting up a development environment <installing_for_devs>`, the typical
+workflow is:
+
+#. Fetch all changes from ``upstream/main``::
+
+    git fetch upstream/main
+
+#. Start a new *feature branch* from ``upstream/main``::
+
+    git checkout -b my-feature upstream/main
+
+#. When you're done editing, e.g., ``lib/matplotlib/collections.py``, record your changes in Git::
+
+     git add lib/matplotlib/collections.py
+     git commit -m 'a commit message'
+
+#. Push the changes to your GitHub fork::
+
+     git push -u origin my-feature
+
+
 .. _update-mirror-main:
 
 Update the ``main`` branch
@@ -49,16 +73,14 @@ Make a new feature branch
 
 When you are ready to make some changes to the code, you should start a new
 branch.  Branches that are for a collection of related edits are often called
-'feature branches'.
-
-Making a new branch for each set of related changes will make it easier for
-someone reviewing your branch to see what you are doing.
+'feature branches'. Making a new branch for each set of related changes will make it
+easier for someone reviewing your branch to see what you are doing.
 
 Choose an informative name for the branch to remind yourself and the rest of us
 what the changes in the branch are for.  For example ``add-ability-to-fly``, or
 ``bugfix-for-issue-42``.
 
-::
+The process for creating a new feature branch is::
 
     # Update the main branch
     git fetch upstream
@@ -130,6 +152,11 @@ Open a pull request
 When you are ready to ask for someone to review your code and consider a merge,
 `submit your Pull Request (PR) <https://docs.github.com/pull-requests>`_.
 
+Go to the web page of *your fork* of the Matplotlib repo, and click
+``Compare & pull request`` to send your changes to the maintainers for review.
+The base repository is ``matplotlib/matplotlib`` and the base branch is
+generally ``main``.
+
 Enter a title for the set of changes with some explanation of what you've done.
 Mention anything you'd like particular attention for - such as a
 complicated change or some code you are not happy with.
@@ -138,6 +165,9 @@ If you don't think your request is ready to be merged, just say so in your pull
 request message and use the "Draft PR" feature of GitHub. This is a good way of
 getting some preliminary code review.
 
+For more guidance on the mechanics of making a pull request, see GitHub's
+`pull request tutorial <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_.
+
 .. _update-pull-request:
 
 Update a pull request

doc/devel/pr_guide.rst

@@ -20,6 +20,8 @@ limited bandwidth. If there is no feedback within a couple of days, please ping
 us by posting a comment to your PR or reaching out on a :ref:`communication channel <communication-channels>`
 
 
+.. _pr-author-guidelines:
+
 Summary for pull request authors
 ================================