diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 7f17a80dc4b6..e857416b13d8 100644 --- 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 - diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst index ad61c43fd348..5911cd860281 100644 --- 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 `_ 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 `_. +2. Filter labels with `"Difficulty: Easy" `_ + & `"Good first Issue" `_ (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 `_ and follow the `pull request guidelines `_. +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 `_. + +.. dropdown:: `Pull request template `_ + :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 `__ 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 `_, 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 index fedf9b76e875..4c71027c75ba 100644 --- 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? ` - - .. grid-item:: - - :octicon:`question;1em;sd-text-info` :ref:`Where should I ask questions? ` - - .. grid-item:: - - :octicon:`git-pull-request;1em;sd-text-info` :ref:`How do I work on an issue? ` - - .. grid-item:: - - :octicon:`codespaces;1em;sd-text-info` :ref:`How do I start a 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? ` + + .. grid-item:: + + :octicon:`question;1em;sd-text-info` :ref:`Where do I ask questions? ` + + .. grid-item:: + + :octicon:`git-pull-request;1em;sd-text-info` :ref:`How do I choose an issue? ` + + .. grid-item:: + + :octicon:`codespaces;1em;sd-text-info` :ref:`How do I start a pull request? ` + + .. _development_environment: Development workflow