matplotlib · story645 · Oct 30, 2024 · Sep 24, 2024 · Sep 24, 2024 · Sep 24, 2024
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -4,11 +4,13 @@ out the development guide https://matplotlib.org/devdocs/devel/index.html
 -->

 ## PR summary
-<!-- Please provide at least 1-2 sentences describing the pull request in detail
-(Why is this change required?  What problem does it solve?) and link to relevant
-issues and PRs.
+<!-- Please describe the pull request, using the questions below as guidance, and link to any relevant issues and PRs:

-Also please summarize the changes in the title, for example "Raise ValueError on
+- Why is this change necessary?
+- What problem does it solve?
+- What is the reasoning for this implementation?
+
+Additionally, please summarize the changes in the title, for example "Raise ValueError on
 non-numeric input to set_xlim" and avoid non-descriptive titles such as "Addresses
 issue #8576".
 -->

diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst
@@ -5,8 +5,6 @@
 ******************
 Contributing guide
 ******************
-
-
 You've discovered a bug or something else you want to change
 in Matplotlib — excellent!

@@ -17,16 +15,8 @@ You want to tell us about it — best of all!
 Below, you can find a number of ways to contribute, and how to connect with the
 Matplotlib community.

-.. _start-contributing:
-
-Get started
-===========
-
-There is no pre-defined pathway for new contributors -- we recommend looking at
-existing issue and pull request discussions, and following the conversations
-during pull request reviews to get context. Or you can deep-dive into a subset
-of the code-base to understand what is going on.
-
+Ways to contribute
+==================
 .. dropdown:: Do I really have something to contribute to Matplotlib?
    :open:
    :icon: person-fill
@@ -106,7 +96,7 @@ Code is contributed through pull requests, so we recommend that you start at
 Documentation
 -------------

-You as an end-user of Matplotlib can make a valuable contribution because you
+You, as an end-user of Matplotlib can make a valuable contribution because you can
 more clearly see the potential for improvement than a core developer. For example,
 you can:

@@ -193,39 +183,19 @@ please cite us following the :doc:`/project/citing` guidelines.
 If you have developed an extension to Matplotlib, please consider adding it to our
 `third party package <https://github.com/matplotlib/mpl-third-party>`_  list.

+.. _new_contributors:

-.. _get_connected:
-
-Get connected
-=============
-When in doubt, we recommend going together! Get connected with our community of
-active contributors, many of whom felt just like you when they started out and
-are happy to welcome you and support you as you get to know how we work, and
-where things are.
-
-.. _contributor_incubator:
-
-Contributor incubator
---------------------
-
-The incubator is our non-public communication channel for new contributors. It
-is a private gitter_ (chat) room moderated by core Matplotlib developers where
-you can get guidance and support for your first few PRs. It's a place where you
-can ask questions about anything: how to use git, GitHub, how our PR review
-process works, technical questions about the code, what makes for good
-documentation or a blog post, how to get involved in community work, or get a
-"pre-review" on your PR.
-
-To join, please go to our public community_ channel, and ask to be added to
-``#incubator``. One of our core developers will see your message and will add you.
+New contributors
+================

-.. _gitter: https://gitter.im/matplotlib/matplotlib
-.. _community: https://gitter.im/matplotlib/community
+There is no pre-defined pathway for new contributors - we recommend looking at
+existing issue and pull request discussions, and following the conversations
+during pull request reviews to get context. Or you can deep-dive into a subset
+of the code-base to understand what is going on.

+.. _new_contributors_meeting:

-.. _new_contributors:
-
-New Contributors Meeting
+New contributors meeting
 ------------------------

 Once a month, we host a meeting to discuss topics that interest new
@@ -241,20 +211,24 @@ questions you might have, and to get to know a few of the people behind the
 GitHub handles 😉. You can reach out to us on gitter_ for any clarifications or
 suggestions. We ❤ feedback!

-.. _managing_issues_prs:
+.. _contributor_incubator:

-Work on an issue
-================
+Contributor incubator
+---------------------

-In general, the Matplotlib project does not assign issues. Issues are
-"assigned" or "claimed" by opening a PR; there is no other assignment
-mechanism. If you have opened such a PR, please comment on the issue thread to
-avoid duplication of work. Please check if there is an existing PR for the
-issue you are addressing. If there is, try to work with the author by
-submitting reviews of their code or commenting on the PR rather than opening
-a new PR; duplicate PRs are subject to being closed.  However, if the existing
-PR is an outline, unlikely to work, or stalled, and the original author is
-unresponsive, feel free to open a new PR referencing the old one.
+The incubator is our non-public communication channel for new contributors. It
+is a private gitter_ (chat) room moderated by core Matplotlib developers where
+you can get guidance and support for your first few PRs. It's a place where you
+can ask questions about anything: how to use git, GitHub, how our PR review
+process works, technical questions about the code, what makes for good
+documentation or a blog post, how to get involved in community work, or get a
+"pre-review" on your PR.
+
+To join, please go to our public community_ channel, and ask to be added to
+``#incubator``. One of our core developers will see your message and will add you.
+
+.. _gitter: https://gitter.im/matplotlib/matplotlib
+.. _community: https://gitter.im/matplotlib/community

 .. _good_first_issues:

@@ -279,6 +253,64 @@ though not necessarily all at the same time:
 - It involves Python features such as decorators and context managers, which
  have subtleties due to our implementation decisions.

+.. _first_contribution:
+
+First contributions
+-------------------
+
+If this is your first open source contribution, or your first time contributing to Matplotlib,
+and you need help or guidance finding a good first issue, look no further. This section will
+guide you through each step:
+
+1. Navigate to the `issues page <https://github.com/matplotlib/matplotlib/issues/>`_.
+2. Filter labels with `"Difficulty: Easy" <https://github.com/matplotlib/matplotlib/labels/Difficulty%3A%20Easy>`_
+   & `"Good first Issue" <https://github.com/matplotlib/matplotlib/labels/good%20first%20issue>`_ (optional).
+3. Click on an issue you would like to work on, and check to see if the issue has a pull request opened to resolve it.
+
+   * A good way to judge if you chose a suitable issue is by asking yourself, "Can I independently submit a PR in 1-2 weeks?"
+4. Check existing pull requests (e.g., :ghpull:`28476`) and filter by the issue number to make sure the issue is not in progress:
+
+   * If the issue has a pull request (is in progress), tag the user working on the issue, and ask to collaborate (optional).
+   * If a pull request does not exist, create a `draft pull request <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests>`_ and follow the `pull request guidelines <https://matplotlib.org/devdocs/devel/pr_guide.html>`_.
+5. Please familiarize yourself with the pull request template (see below),
+   and ensure you understand/are able to complete the template when you open your pull request.
+   Additional information can be found in the `pull request guidelines <https://matplotlib.org/devdocs/devel/pr_guide.html>`_.
+
+.. dropdown:: `Pull request template <https://github.com/matplotlib/matplotlib/blob/main/.github/PULL_REQUEST_TEMPLATE.md>`_
+    :open:
+
+    .. literalinclude:: ../../.github/PULL_REQUEST_TEMPLATE.md
+       :language: markdown
+
+.. _get_connected:
+
+Get connected
+=============
+
+When in doubt, we recommend going together! Get connected with our community of
+active contributors, many of whom felt just like you when they started out and
+are happy to welcome you and support you as you get to know how we work, and
+where things are. You can reach out on any of our :ref:`communication-channels`.
+For development questions we recommend reaching out on our development gitter_
+chat room and for community questions reach out at community_.
+
+.. _gitter: https://gitter.im/matplotlib/matplotlib
+.. _community: https://gitter.im/matplotlib/community
+
+.. _managing_issues_prs:
+
+Choose an issue
+===============
+
+In general, the Matplotlib project does not assign issues. Issues are
+"assigned" or "claimed" by opening a PR; there is no other assignment
+mechanism. If you have opened such a PR, please comment on the issue thread to
+avoid duplication of work. Please check if there is an existing PR for the
+issue you are addressing. If there is, try to work with the author by
+submitting reviews of their code or commenting on the PR rather than opening
+a new PR; duplicate PRs are subject to being closed.  However, if the existing
+PR is an outline, unlikely to work, or stalled, and the original author is
+unresponsive, feel free to open a new PR referencing the old one.

 .. _how-to-pull-request:

@@ -288,7 +320,7 @@ 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
-Maplotlib repository to your own computer, or alternatively using
+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.
@@ -352,14 +384,14 @@ A brief overview of the workflow is as follows.
   e.g., ``lib/matplotlib/collections.py``, do::

     git add lib/matplotlib/collections.py
-     git commit
+     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
@@ -378,14 +410,13 @@ Check the `GitHub instructions
 for more details on connecting to the desktop.

 View documentation
-""""""""""""""""""
+''''''''''''''''''

 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."

-
 Open a pull request on Matplotlib
 ---------------------------------


diff --git a/doc/devel/index.rst b/doc/devel/index.rst
@@ -86,27 +86,6 @@ to contributing, we recommend that you first read our
 .. grid:: 1 1 2 2
   :class-row: sd-fs-5 sd-align-minor-center

-   .. grid-item::
-
-      .. grid:: 1
-         :gutter: 1
-
-         .. grid-item::
-
-            :octicon:`info;1em;sd-text-info` :ref:`Where should I start? <start-contributing>`
-
-         .. grid-item::
-
-            :octicon:`question;1em;sd-text-info` :ref:`Where should I ask questions? <get_connected>`
-
-         .. grid-item::
-
-            :octicon:`git-pull-request;1em;sd-text-info` :ref:`How do I work on an issue? <managing_issues_prs>`
-
-         .. grid-item::
-
-            :octicon:`codespaces;1em;sd-text-info` :ref:`How do I start a pull request? <how-to-pull-request>`
-
   .. grid-item::

      .. grid:: 1
@@ -144,6 +123,28 @@ to contributing, we recommend that you first read our

            :octicon:`globe;1em;sd-text-info` Build community

+   .. grid-item::
+
+      .. grid:: 1
+         :gutter: 1
+
+         .. grid-item::
+
+            :octicon:`info;1em;sd-text-info` :ref:`Is this my first contribution? <new_contributors>`
+
+         .. grid-item::
+
+            :octicon:`question;1em;sd-text-info` :ref:`Where do I ask questions? <get_connected>`
+
+         .. grid-item::
+
+            :octicon:`git-pull-request;1em;sd-text-info` :ref:`How do I choose an issue? <managing_issues_prs>`
+
+         .. grid-item::
+
+            :octicon:`codespaces;1em;sd-text-info` :ref:`How do I start a pull request? <how-to-pull-request>`
+
+
 .. _development_environment:

 Development workflow