From 100a42b767656724343a3d916780ab54d5316119 Mon Sep 17 00:00:00 2001 From: anpaulan Date: Tue, 24 Sep 2024 00:51:58 -0400 Subject: [PATCH 01/17] udpated contribution doc #28476 --- doc/devel/contribute.rst | 366 +++++++++++++++++++++------------------ doc/devel/index.rst | 6 +- 2 files changed, 197 insertions(+), 175 deletions(-) diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst index ad61c43fd348..31b3eac5e621 100644 --- a/doc/devel/contribute.rst +++ b/doc/devel/contribute.rst @@ -3,7 +3,7 @@ .. _contributing: ****************** -Contributing guide +Contribution guide ****************** @@ -27,177 +27,10 @@ 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. -.. dropdown:: Do I really have something to contribute to Matplotlib? - :open: - :icon: person-fill - - 100% yes! There are so many ways to contribute to our community. Take a look - at the following sections to learn more. - - There are a few typical new contributor profiles: - - * **You are a Matplotlib user, and you see a bug, a potential improvement, or - something that annoys you, and you can fix it.** - - You can search our issue tracker for an existing issue that describes your problem or - open a new issue to inform us of the problem you observed and discuss the best approach - to fix it. If your contributions would not be captured on GitHub (social media, - communication, educational content), you can also reach out to us on gitter_, - `Discourse `__ or attend any of our `community - meetings `__. - - * **You are not a regular Matplotlib user but a domain expert: you know about - visualization, 3D plotting, design, technical writing, statistics, or some - other field where Matplotlib could be improved.** - - Awesome -- you have a focus on a specific application and domain and can - start there. In this case, maintainers can help you figure out the best - implementation; open an issue or pull request with a starting point, and we'll - be happy to discuss technical approaches. - - If you prefer, you can use the `GitHub functionality for "draft" pull requests - `__ - and request early feedback on whatever you are working on, but you should be - aware that maintainers may not review your contribution unless it has the - "Ready to review" state on GitHub. - - * **You are new to Matplotlib, both as a user and contributor, and want to start - contributing but have yet to develop a particular interest.** - - Having some previous experience or relationship with the library can be very - helpful when making open-source contributions. It helps you understand why - things are the way they are and how they *should* be. Having first-hand - experience and context is valuable both for what you can bring to the - conversation (and given the breadth of Matplotlib's usage, there is a good - chance it is a unique context in any given conversation) and make it easier to - understand where other people are coming from. - - Understanding the entire codebase is a long-term project, and nobody expects - you to do this right away. If you are determined to get started with - Matplotlib and want to learn, going through the basic functionality, - choosing something to focus on (3d, testing, documentation, animations, etc.) - and gaining context on this area by reading the issues and pull requests - touching these subjects is a reasonable approach. - -.. _contribute_code: - -Code ----- -You want to implement a feature or fix a bug or help with maintenance - much -appreciated! Our library source code is found in: - -* Python library code: :file:`lib/` -* C-extension code: :file:`src/` -* Tests: :file:`lib/matplotlib/tests/` - -Because many people use and work on Matplotlib, we have guidelines for keeping -our code consistent and mitigating the impact of changes. - -* :ref:`coding_guidelines` -* :ref:`api_changes` -* :ref:`pr-guidelines` - -Code is contributed through pull requests, so we recommend that you start at -:ref:`how-to-pull-request` If you get stuck, please reach out on the -:ref:`contributor_incubator` - -.. _contribute_documentation: - -Documentation -------------- - -You as an end-user of Matplotlib can make a valuable contribution because you -more clearly see the potential for improvement than a core developer. For example, -you can: - -- Fix a typo -- Clarify a docstring -- Write or update an :ref:`example plot ` -- Write or update a comprehensive :ref:`tutorial ` - -Our code is documented inline in the source code files in :file:`matplotlib/lib`. -Our website structure mirrors our folder structure, meaning that a narrative -document's URL roughly corresponds to its location in our folder structure: - -.. grid:: 1 1 2 2 - - .. grid-item:: using the library - - * :file:`galleries/plot_types/` - * :file:`users/getting_started/` - * :file:`galleries/user_explain/` - * :file:`galleries/tutorials/` - * :file:`galleries/examples/` - * :file:`doc/api/` - - .. grid-item:: information about the library - - * :file:`doc/install/` - * :file:`doc/project/` - * :file:`doc/devel/` - * :file:`doc/users/resources/index.rst` - * :file:`doc/users/faq.rst` - - -Other documentation is generated from the following external sources: - -* matplotlib.org homepage: https://github.com/matplotlib/mpl-brochure-site -* cheat sheets: https://github.com/matplotlib/cheatsheets -* third party packages: https://github.com/matplotlib/mpl-third-party - -Instructions and guidelines for contributing documentation are found in: - -* :doc:`document` -* :doc:`style_guide` -* :doc:`tag_guidelines` - -Documentation is contributed through pull requests, so we recommend that you start -at :ref:`how-to-pull-request`. If that feels intimidating, we encourage you to -`open an issue`_ describing what improvements you would make. If you get stuck, -please reach out on the :ref:`contributor_incubator` - -.. _`open an issue`: https://github.com/matplotlib/matplotlib/issues/new?assignees=&labels=Documentation&projects=&template=documentation.yml&title=%5BDoc%5D%3A+ - -.. _contribute_triage: - -Triage ------- -We appreciate your help keeping the `issue tracker `_ -organized because it is our centralized location for feature requests, -bug reports, tracking major projects, and discussing priorities. Some examples of what -we mean by triage are: - -* labeling issues and pull requests -* verifying bug reports -* debugging and resolving issues -* linking to related issues, discussion, and external work - -Our triage process is discussed in detail in :ref:`bug_triaging`. - -If you have any questions about the process, please reach out on the -:ref:`contributor_incubator` - -.. _other_ways_to_contribute: - -Community ---------- -Matplotlib's community is built by its members, if you would like to help out -see our :ref:`communications-guidelines`. - -It helps us if you spread the word: reference the project from your blog -and articles or link to it from your website! - -If Matplotlib contributes to a project that leads to a scientific publication, -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. - - .. _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 @@ -243,8 +76,8 @@ suggestions. We ❤ feedback! .. _managing_issues_prs: -Work on an issue -================ +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 @@ -279,11 +112,27 @@ 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 & New Contributors +-------------------------------------- + +If this is your first open source contribution, or 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 is already claimed. +4. If the issue is claimed, tag the user working on the issue, +5. and ask to collaborate (optional). +6. Check the `pull requests (i.e. #28476) `_ and filter by the issue number to make sure the issue is not in progress. +7. After steps 3 & 4 are done, and no one is working on the issue, comment on the issue to state you are working on it. .. _how-to-pull-request: Start a pull request -==================== +-------------------- The preferred way to contribute to Matplotlib is to fork the `main repository `__ on GitHub, @@ -398,3 +247,176 @@ generally ``main``. For more guidance, see GitHub's `pull request tutorial 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`. + +Ways to contribute +================== +.. dropdown:: Do I really have something to contribute to Matplotlib? + :open: + :icon: person-fill + + 100% yes! There are so many ways to contribute to our community. Take a look + at the following sections to learn more. + + There are a few typical new contributor profiles: + + * **You are a Matplotlib user, and you see a bug, a potential improvement, or + something that annoys you, and you can fix it.** + + You can search our issue tracker for an existing issue that describes your problem or + open a new issue to inform us of the problem you observed and discuss the best approach + to fix it. If your contributions would not be captured on GitHub (social media, + communication, educational content), you can also reach out to us on gitter_, + `Discourse `__ or attend any of our `community + meetings `__. + + * **You are not a regular Matplotlib user but a domain expert: you know about + visualization, 3D plotting, design, technical writing, statistics, or some + other field where Matplotlib could be improved.** + + Awesome -- you have a focus on a specific application and domain and can + start there. In this case, maintainers can help you figure out the best + implementation; open an issue or pull request with a starting point, and we'll + be happy to discuss technical approaches. + + If you prefer, you can use the `GitHub functionality for "draft" pull requests + `__ + and request early feedback on whatever you are working on, but you should be + aware that maintainers may not review your contribution unless it has the + "Ready to review" state on GitHub. + + * **You are new to Matplotlib, both as a user and contributor, and want to start + contributing but have yet to develop a particular interest.** + + Having some previous experience or relationship with the library can be very + helpful when making open-source contributions. It helps you understand why + things are the way they are and how they *should* be. Having first-hand + experience and context is valuable both for what you can bring to the + conversation (and given the breadth of Matplotlib's usage, there is a good + chance it is a unique context in any given conversation) and make it easier to + understand where other people are coming from. + + Understanding the entire codebase is a long-term project, and nobody expects + you to do this right away. If you are determined to get started with + Matplotlib and want to learn, going through the basic functionality, + choosing something to focus on (3d, testing, documentation, animations, etc.) + and gaining context on this area by reading the issues and pull requests + touching these subjects is a reasonable approach. + +.. _contribute_code: + +Code +---- +You want to implement a feature or fix a bug or help with maintenance - much +appreciated! Our library source code is found in: + +* Python library code: :file:`lib/` +* C-extension code: :file:`src/` +* Tests: :file:`lib/matplotlib/tests/` + +Because many people use and work on Matplotlib, we have guidelines for keeping +our code consistent and mitigating the impact of changes. + +* :ref:`coding_guidelines` +* :ref:`api_changes` +* :ref:`pr-guidelines` + +Code is contributed through pull requests, so we recommend that you start at +:ref:`how-to-pull-request` If you get stuck, please reach out on the +:ref:`contributor_incubator` + +.. _contribute_documentation: + +Documentation +------------- + +You as an end-user of Matplotlib can make a valuable contribution because you +more clearly see the potential for improvement than a core developer. For example, +you can: + +- Fix a typo +- Clarify a docstring +- Write or update an :ref:`example plot ` +- Write or update a comprehensive :ref:`tutorial ` + +Our code is documented inline in the source code files in :file:`matplotlib/lib`. +Our website structure mirrors our folder structure, meaning that a narrative +document's URL roughly corresponds to its location in our folder structure: + +.. grid:: 1 1 2 2 + + .. grid-item:: using the library + + * :file:`galleries/plot_types/` + * :file:`users/getting_started/` + * :file:`galleries/user_explain/` + * :file:`galleries/tutorials/` + * :file:`galleries/examples/` + * :file:`doc/api/` + + .. grid-item:: information about the library + + * :file:`doc/install/` + * :file:`doc/project/` + * :file:`doc/devel/` + * :file:`doc/users/resources/index.rst` + * :file:`doc/users/faq.rst` + + +Other documentation is generated from the following external sources: + +* matplotlib.org homepage: https://github.com/matplotlib/mpl-brochure-site +* cheat sheets: https://github.com/matplotlib/cheatsheets +* third party packages: https://github.com/matplotlib/mpl-third-party + +Instructions and guidelines for contributing documentation are found in: + +* :doc:`document` +* :doc:`style_guide` +* :doc:`tag_guidelines` + +Documentation is contributed through pull requests, so we recommend that you start +at :ref:`how-to-pull-request`. If that feels intimidating, we encourage you to +`open an issue`_ describing what improvements you would make. If you get stuck, +please reach out on the :ref:`contributor_incubator` + +.. _`open an issue`: https://github.com/matplotlib/matplotlib/issues/new?assignees=&labels=Documentation&projects=&template=documentation.yml&title=%5BDoc%5D%3A+ + +.. _contribute_triage: + +Triage +------ +We appreciate your help keeping the `issue tracker `_ +organized because it is our centralized location for feature requests, +bug reports, tracking major projects, and discussing priorities. Some examples of what +we mean by triage are: + +* labeling issues and pull requests +* verifying bug reports +* debugging and resolving issues +* linking to related issues, discussion, and external work + +Our triage process is discussed in detail in :ref:`bug_triaging`. + +If you have any questions about the process, please reach out on the +:ref:`contributor_incubator` + +.. _other_ways_to_contribute: + +Community +--------- +Matplotlib's community is built by its members, if you would like to help out +see our :ref:`communications-guidelines`. + +It helps us if you spread the word: reference the project from your blog +and articles or link to it from your website! + +If Matplotlib contributes to a project that leads to a scientific publication, +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. + + + + + diff --git a/doc/devel/index.rst b/doc/devel/index.rst index fedf9b76e875..ff2e5b9feb89 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -71,7 +71,7 @@ Since Matplotlib is an open source project with limited resources, we encourage to also :ref:`participate ` in fixing bugs and implementing new features. -Contributing guide +Contribution guide ================== We welcome you to get more involved with the Matplotlib project! If you are new @@ -101,12 +101,12 @@ to contributing, we recommend that you first read our .. grid-item:: - :octicon:`git-pull-request;1em;sd-text-info` :ref:`How do I work on an issue? ` + :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? ` - + .. grid-item:: .. grid:: 1 From e8a4e3818aa5f82a431508e004a9ba7fa31d80b3 Mon Sep 17 00:00:00 2001 From: anpaulan Date: Tue, 24 Sep 2024 01:03:27 -0400 Subject: [PATCH 02/17] udpated contribution doc #28476 --- doc/devel/contribute.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst index 31b3eac5e621..45c0f857e64d 100644 --- a/doc/devel/contribute.rst +++ b/doc/devel/contribute.rst @@ -124,10 +124,9 @@ 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 is already claimed. -4. If the issue is claimed, tag the user working on the issue, -5. and ask to collaborate (optional). -6. Check the `pull requests (i.e. #28476) `_ and filter by the issue number to make sure the issue is not in progress. -7. After steps 3 & 4 are done, and no one is working on the issue, comment on the issue to state you are working on it. +4. If the issue is claimed, tag the user working on the issue, and ask to collaborate (optional). +5. Check the `pull requests (i.e. #28476) `_ and filter by the issue number to make sure the issue is not in progress. +6. After steps 3 & 4 are done, and no one is working on the issue, comment on the issue to state you are working on it. .. _how-to-pull-request: @@ -301,7 +300,7 @@ Ways to contribute choosing something to focus on (3d, testing, documentation, animations, etc.) and gaining context on this area by reading the issues and pull requests touching these subjects is a reasonable approach. - + .. _contribute_code: Code From ddf47ff6e641e24a73d0935217fc68db34c1946e Mon Sep 17 00:00:00 2001 From: anpaulan Date: Tue, 24 Sep 2024 18:19:39 -0400 Subject: [PATCH 03/17] used pre-install to fix failed checks --- doc/devel/contribute.rst | 7 +------ doc/devel/index.rst | 4 ++-- 2 files changed, 3 insertions(+), 8 deletions(-) diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst index 45c0f857e64d..7ebf65890b0e 100644 --- a/doc/devel/contribute.rst +++ b/doc/devel/contribute.rst @@ -118,7 +118,7 @@ First Contributions & New Contributors -------------------------------------- If this is your first open source contribution, or first time contributing to Matplotlib, -and you need help or guidance finding a good first issue, look no further. This section will +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 `_. @@ -414,8 +414,3 @@ 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. - - - - - diff --git a/doc/devel/index.rst b/doc/devel/index.rst index ff2e5b9feb89..f6c1bcc7ec8d 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -71,7 +71,7 @@ Since Matplotlib is an open source project with limited resources, we encourage to also :ref:`participate ` in fixing bugs and implementing new features. -Contribution guide +Contribution guide ================== We welcome you to get more involved with the Matplotlib project! If you are new @@ -106,7 +106,7 @@ to contributing, we recommend that you first read our .. grid-item:: :octicon:`codespaces;1em;sd-text-info` :ref:`How do I start a pull request? ` - + .. grid-item:: .. grid:: 1 From 6fe4618c898da7d6da44ac41dfc3cbf19dd93644 Mon Sep 17 00:00:00 2001 From: anpaulan Date: Fri, 27 Sep 2024 23:55:10 -0400 Subject: [PATCH 04/17] reorganized contribution doc --- doc/devel/contribute.rst | 433 ++++++++++++++++++++------------------- 1 file changed, 218 insertions(+), 215 deletions(-) diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst index 7ebf65890b0e..6c9e57f81fd3 100644 --- a/doc/devel/contribute.rst +++ b/doc/devel/contribute.rst @@ -27,10 +27,178 @@ 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 + + 100% yes! There are so many ways to contribute to our community. Take a look + at the following sections to learn more. + + There are a few typical new contributor profiles: + + * **You are a Matplotlib user, and you see a bug, a potential improvement, or + something that annoys you, and you can fix it.** + + You can search our issue tracker for an existing issue that describes your problem or + open a new issue to inform us of the problem you observed and discuss the best approach + to fix it. If your contributions would not be captured on GitHub (social media, + communication, educational content), you can also reach out to us on gitter_, + `Discourse `__ or attend any of our `community + meetings `__. + + * **You are not a regular Matplotlib user but a domain expert: you know about + visualization, 3D plotting, design, technical writing, statistics, or some + other field where Matplotlib could be improved.** + + Awesome -- you have a focus on a specific application and domain and can + start there. In this case, maintainers can help you figure out the best + implementation; open an issue or pull request with a starting point, and we'll + be happy to discuss technical approaches. + + If you prefer, you can use the `GitHub functionality for "draft" pull requests + `__ + and request early feedback on whatever you are working on, but you should be + aware that maintainers may not review your contribution unless it has the + "Ready to review" state on GitHub. + + * **You are new to Matplotlib, both as a user and contributor, and want to start + contributing but have yet to develop a particular interest.** + + Having some previous experience or relationship with the library can be very + helpful when making open-source contributions. It helps you understand why + things are the way they are and how they *should* be. Having first-hand + experience and context is valuable both for what you can bring to the + conversation (and given the breadth of Matplotlib's usage, there is a good + chance it is a unique context in any given conversation) and make it easier to + understand where other people are coming from. + + Understanding the entire codebase is a long-term project, and nobody expects + you to do this right away. If you are determined to get started with + Matplotlib and want to learn, going through the basic functionality, + choosing something to focus on (3d, testing, documentation, animations, etc.) + and gaining context on this area by reading the issues and pull requests + touching these subjects is a reasonable approach. + +.. _contribute_code: + +Code +---- +You want to implement a feature or fix a bug or help with maintenance - much +appreciated! Our library source code is found in: + +* Python library code: :file:`lib/` +* C-extension code: :file:`src/` +* Tests: :file:`lib/matplotlib/tests/` + +Because many people use and work on Matplotlib, we have guidelines for keeping +our code consistent and mitigating the impact of changes. + +* :ref:`coding_guidelines` +* :ref:`api_changes` +* :ref:`pr-guidelines` + +Code is contributed through pull requests, so we recommend that you start at +:ref:`how-to-pull-request` If you get stuck, please reach out on the +:ref:`contributor_incubator` + +.. _contribute_documentation: + +Documentation +------------- + +You as an end-user of Matplotlib can make a valuable contribution because you +more clearly see the potential for improvement than a core developer. For example, +you can: + +- Fix a typo +- Clarify a docstring +- Write or update an :ref:`example plot ` +- Write or update a comprehensive :ref:`tutorial ` + +Our code is documented inline in the source code files in :file:`matplotlib/lib`. +Our website structure mirrors our folder structure, meaning that a narrative +document's URL roughly corresponds to its location in our folder structure: + +.. grid:: 1 1 2 2 + + .. grid-item:: using the library + + * :file:`galleries/plot_types/` + * :file:`users/getting_started/` + * :file:`galleries/user_explain/` + * :file:`galleries/tutorials/` + * :file:`galleries/examples/` + * :file:`doc/api/` + + .. grid-item:: information about the library + + * :file:`doc/install/` + * :file:`doc/project/` + * :file:`doc/devel/` + * :file:`doc/users/resources/index.rst` + * :file:`doc/users/faq.rst` + + +Other documentation is generated from the following external sources: + +* matplotlib.org homepage: https://github.com/matplotlib/mpl-brochure-site +* cheat sheets: https://github.com/matplotlib/cheatsheets +* third party packages: https://github.com/matplotlib/mpl-third-party + +Instructions and guidelines for contributing documentation are found in: + +* :doc:`document` +* :doc:`style_guide` +* :doc:`tag_guidelines` + +Documentation is contributed through pull requests, so we recommend that you start +at :ref:`how-to-pull-request`. If that feels intimidating, we encourage you to +`open an issue`_ describing what improvements you would make. If you get stuck, +please reach out on the :ref:`contributor_incubator` + +.. _`open an issue`: https://github.com/matplotlib/matplotlib/issues/new?assignees=&labels=Documentation&projects=&template=documentation.yml&title=%5BDoc%5D%3A+ + +.. _contribute_triage: + +Triage +------ +We appreciate your help keeping the `issue tracker `_ +organized because it is our centralized location for feature requests, +bug reports, tracking major projects, and discussing priorities. Some examples of what +we mean by triage are: + +* labeling issues and pull requests +* verifying bug reports +* debugging and resolving issues +* linking to related issues, discussion, and external work + +Our triage process is discussed in detail in :ref:`bug_triaging`. + +If you have any questions about the process, please reach out on the +:ref:`contributor_incubator` + +.. _other_ways_to_contribute: + +Community +--------- +Matplotlib's community is built by its members, if you would like to help out +see our :ref:`communications-guidelines`. + +It helps us if you spread the word: reference the project from your blog +and articles or link to it from your website! + +If Matplotlib contributes to a project that leads to a scientific publication, +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. + .. _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 @@ -55,25 +223,6 @@ To join, please go to our public community_ channel, and ask to be added to .. _gitter: https://gitter.im/matplotlib/matplotlib .. _community: https://gitter.im/matplotlib/community - -.. _new_contributors: - -New Contributors Meeting ------------------------- - -Once a month, we host a meeting to discuss topics that interest new -contributors. Anyone can attend, present, or sit in and listen to the call. -Among our attendees are fellow new contributors, as well as maintainers, and -veteran contributors, who are keen to support onboarding of new folks and -share their experience. You can find our community calendar link at the -`Scientific Python website `_, and -you can browse previous meeting notes on `GitHub -`_. -We recommend joining the meeting to clarify any doubts, or lingering -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: Choose an issue @@ -89,45 +238,6 @@ 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. -.. _good_first_issues: - -Good first issues ------------------ - -While any contributions are welcome, we have marked some issues as -particularly suited for new contributors by the label `good first issue -`_. These -are well documented issues, that do not require a deep understanding of the -internals of Matplotlib. The issues may additionally be tagged with a -difficulty. ``Difficulty: Easy`` is suited for people with little Python -experience. ``Difficulty: Medium`` and ``Difficulty: Hard`` require more -programming experience. This could be for a variety of reasons, among them, -though not necessarily all at the same time: - -- The issue is in areas of the code base which have more interdependencies, - or legacy code. -- It has less clearly defined tasks, which require some independent - exploration, making suggestions, or follow-up discussions to clarify a good - path to resolve the issue. -- It involves Python features such as decorators and context managers, which - have subtleties due to our implementation decisions. - -.. _first_contribution: - -First Contributions & New Contributors --------------------------------------- - -If this is your first open source contribution, or 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 is already claimed. -4. If the issue is claimed, tag the user working on the issue, and ask to collaborate (optional). -5. Check the `pull requests (i.e. #28476) `_ and filter by the issue number to make sure the issue is not in progress. -6. After steps 3 & 4 are done, and no one is working on the issue, comment on the issue to state you are working on it. - .. _how-to-pull-request: Start a pull request @@ -233,7 +343,6 @@ 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 --------------------------------- @@ -247,170 +356,64 @@ 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`. -Ways to contribute -================== -.. dropdown:: Do I really have something to contribute to Matplotlib? - :open: - :icon: person-fill - - 100% yes! There are so many ways to contribute to our community. Take a look - at the following sections to learn more. - - There are a few typical new contributor profiles: - - * **You are a Matplotlib user, and you see a bug, a potential improvement, or - something that annoys you, and you can fix it.** - - You can search our issue tracker for an existing issue that describes your problem or - open a new issue to inform us of the problem you observed and discuss the best approach - to fix it. If your contributions would not be captured on GitHub (social media, - communication, educational content), you can also reach out to us on gitter_, - `Discourse `__ or attend any of our `community - meetings `__. - - * **You are not a regular Matplotlib user but a domain expert: you know about - visualization, 3D plotting, design, technical writing, statistics, or some - other field where Matplotlib could be improved.** - - Awesome -- you have a focus on a specific application and domain and can - start there. In this case, maintainers can help you figure out the best - implementation; open an issue or pull request with a starting point, and we'll - be happy to discuss technical approaches. - - If you prefer, you can use the `GitHub functionality for "draft" pull requests - `__ - and request early feedback on whatever you are working on, but you should be - aware that maintainers may not review your contribution unless it has the - "Ready to review" state on GitHub. - - * **You are new to Matplotlib, both as a user and contributor, and want to start - contributing but have yet to develop a particular interest.** - - Having some previous experience or relationship with the library can be very - helpful when making open-source contributions. It helps you understand why - things are the way they are and how they *should* be. Having first-hand - experience and context is valuable both for what you can bring to the - conversation (and given the breadth of Matplotlib's usage, there is a good - chance it is a unique context in any given conversation) and make it easier to - understand where other people are coming from. - - Understanding the entire codebase is a long-term project, and nobody expects - you to do this right away. If you are determined to get started with - Matplotlib and want to learn, going through the basic functionality, - choosing something to focus on (3d, testing, documentation, animations, etc.) - and gaining context on this area by reading the issues and pull requests - touching these subjects is a reasonable approach. - -.. _contribute_code: - -Code ----- -You want to implement a feature or fix a bug or help with maintenance - much -appreciated! Our library source code is found in: - -* Python library code: :file:`lib/` -* C-extension code: :file:`src/` -* Tests: :file:`lib/matplotlib/tests/` - -Because many people use and work on Matplotlib, we have guidelines for keeping -our code consistent and mitigating the impact of changes. - -* :ref:`coding_guidelines` -* :ref:`api_changes` -* :ref:`pr-guidelines` - -Code is contributed through pull requests, so we recommend that you start at -:ref:`how-to-pull-request` If you get stuck, please reach out on the -:ref:`contributor_incubator` - -.. _contribute_documentation: - -Documentation -------------- - -You as an end-user of Matplotlib can make a valuable contribution because you -more clearly see the potential for improvement than a core developer. For example, -you can: - -- Fix a typo -- Clarify a docstring -- Write or update an :ref:`example plot ` -- Write or update a comprehensive :ref:`tutorial ` - -Our code is documented inline in the source code files in :file:`matplotlib/lib`. -Our website structure mirrors our folder structure, meaning that a narrative -document's URL roughly corresponds to its location in our folder structure: - -.. grid:: 1 1 2 2 - - .. grid-item:: using the library - - * :file:`galleries/plot_types/` - * :file:`users/getting_started/` - * :file:`galleries/user_explain/` - * :file:`galleries/tutorials/` - * :file:`galleries/examples/` - * :file:`doc/api/` - - .. grid-item:: information about the library - - * :file:`doc/install/` - * :file:`doc/project/` - * :file:`doc/devel/` - * :file:`doc/users/resources/index.rst` - * :file:`doc/users/faq.rst` - - -Other documentation is generated from the following external sources: - -* matplotlib.org homepage: https://github.com/matplotlib/mpl-brochure-site -* cheat sheets: https://github.com/matplotlib/cheatsheets -* third party packages: https://github.com/matplotlib/mpl-third-party - -Instructions and guidelines for contributing documentation are found in: - -* :doc:`document` -* :doc:`style_guide` -* :doc:`tag_guidelines` +.. _new_contributors: -Documentation is contributed through pull requests, so we recommend that you start -at :ref:`how-to-pull-request`. If that feels intimidating, we encourage you to -`open an issue`_ describing what improvements you would make. If you get stuck, -please reach out on the :ref:`contributor_incubator` +First Open Source Contribution & New Contributors +================================================= -.. _`open an issue`: https://github.com/matplotlib/matplotlib/issues/new?assignees=&labels=Documentation&projects=&template=documentation.yml&title=%5BDoc%5D%3A+ +.. _new_contributors_meeting: -.. _contribute_triage: +New Contributors Meeting +------------------------ -Triage ------- -We appreciate your help keeping the `issue tracker `_ -organized because it is our centralized location for feature requests, -bug reports, tracking major projects, and discussing priorities. Some examples of what -we mean by triage are: +Once a month, we host a meeting to discuss topics that interest new +contributors. Anyone can attend, present, or sit in and listen to the call. +Among our attendees are fellow new contributors, as well as maintainers, and +veteran contributors, who are keen to support onboarding of new folks and +share their experience. You can find our community calendar link at the +`Scientific Python website `_, and +you can browse previous meeting notes on `GitHub +`_. +We recommend joining the meeting to clarify any doubts, or lingering +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! -* labeling issues and pull requests -* verifying bug reports -* debugging and resolving issues -* linking to related issues, discussion, and external work +.. _good_first_issues: -Our triage process is discussed in detail in :ref:`bug_triaging`. +Good first issues +----------------- -If you have any questions about the process, please reach out on the -:ref:`contributor_incubator` +While any contributions are welcome, we have marked some issues as +particularly suited for new contributors by the label `good first issue +`_. These +are well documented issues, that do not require a deep understanding of the +internals of Matplotlib. The issues may additionally be tagged with a +difficulty. ``Difficulty: Easy`` is suited for people with little Python +experience. ``Difficulty: Medium`` and ``Difficulty: Hard`` require more +programming experience. This could be for a variety of reasons, among them, +though not necessarily all at the same time: -.. _other_ways_to_contribute: +- The issue is in areas of the code base which have more interdependencies, + or legacy code. +- It has less clearly defined tasks, which require some independent + exploration, making suggestions, or follow-up discussions to clarify a good + path to resolve the issue. +- It involves Python features such as decorators and context managers, which + have subtleties due to our implementation decisions. -Community ---------- -Matplotlib's community is built by its members, if you would like to help out -see our :ref:`communications-guidelines`. +.. _first_contribution: -It helps us if you spread the word: reference the project from your blog -and articles or link to it from your website! +First Contributions +------------------- -If Matplotlib contributes to a project that leads to a scientific publication, -please cite us following the :doc:`/project/citing` guidelines. +If this is your first open source contribution, or 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. -If you have developed an extension to Matplotlib, please consider adding it to our -`third party package `_ list. +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 a PR has been opened to resolve the issue. +4. If the issue is a work in progress, tag the user working on the issue, and ask to collaborate (optional). +5. Check the pull requests (i.e. :ghpull:`28476`) and filter by the issue number to make sure the issue is not in progress. +6. After steps 3 & 5 are done, and a PR does not exist, open a 'draft (incomeplete) PR '_. From 6c85c92d2f0a6685ef77095d9aa8b9172da407a7 Mon Sep 17 00:00:00 2001 From: anpaulan Date: Wed, 2 Oct 2024 14:02:40 -0400 Subject: [PATCH 05/17] updated text and embdedded links render properly --- doc/devel/contribute.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst index 6c9e57f81fd3..851bf8d5b610 100644 --- a/doc/devel/contribute.rst +++ b/doc/devel/contribute.rst @@ -416,4 +416,4 @@ guide you through each step. 3. Click on an issue you would like to work on, and check to see if the issue a PR has been opened to resolve the issue. 4. If the issue is a work in progress, tag the user working on the issue, and ask to collaborate (optional). 5. Check the pull requests (i.e. :ghpull:`28476`) and filter by the issue number to make sure the issue is not in progress. -6. After steps 3 & 5 are done, and a PR does not exist, open a 'draft (incomeplete) PR '_. +6. After steps 3 & 5 are done, and a PR does not exist, create a `draft PR `_ and follow the `pull request guidelines `_ . From ae2d80bb89bed0645215ca7c59ab37a2b1afddd0 Mon Sep 17 00:00:00 2001 From: anpaulan Date: Sat, 12 Oct 2024 10:22:03 -0400 Subject: [PATCH 06/17] updated guide structure and index cards --- doc/devel/contribute.rst | 162 +++++++++++++++++++-------------------- doc/devel/index.rst | 44 ++++++----- 2 files changed, 102 insertions(+), 104 deletions(-) diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst index 851bf8d5b610..7ac9a95cda99 100644 --- a/doc/devel/contribute.rst +++ b/doc/devel/contribute.rst @@ -17,16 +17,6 @@ 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? @@ -195,20 +185,88 @@ 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: + +New Contributors +================ + +.. _new_contributors_meeting: + +New Contributors Meeting +------------------------ + +Once a month, we host a meeting to discuss topics that interest new +contributors. Anyone can attend, present, or sit in and listen to the call. +Among our attendees are fellow new contributors, as well as maintainers, and +veteran contributors, who are keen to support onboarding of new folks and +share their experience. You can find our community calendar link at the +`Scientific Python website `_, and +you can browse previous meeting notes on `GitHub +`_. +We recommend joining the meeting to clarify any doubts, or lingering +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! + +.. _good_first_issues: + +Good first issues +----------------- + +While any contributions are welcome, we have marked some issues as +particularly suited for new contributors by the label `good first issue +`_. These +are well documented issues, that do not require a deep understanding of the +internals of Matplotlib. The issues may additionally be tagged with a +difficulty. ``Difficulty: Easy`` is suited for people with little Python +experience. ``Difficulty: Medium`` and ``Difficulty: Hard`` require more +programming experience. This could be for a variety of reasons, among them, +though not necessarily all at the same time: + +- The issue is in areas of the code base which have more interdependencies, + or legacy code. +- It has less clearly defined tasks, which require some independent + exploration, making suggestions, or follow-up discussions to clarify a good + path to resolve the issue. +- 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 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 a PR has been opened to resolve the issue. +4. If the issue is a work in progress, tag the user working on the issue, and ask to collaborate (optional). +5. Check the pull requests (i.e. :ghpull:`28476`) and filter by the issue number to make sure the issue is not in progress. +6. After steps 3 & 5 are done, and a PR does not exist, create a `draft PR `_ and follow the `pull request guidelines `_ . + +.. _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. + .. _get_connected: -Get connected -============= +Get connected: Contributor incubator +------------------------------------ + 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 @@ -252,7 +310,7 @@ in-browser development environment that comes with the appropriate setup to contribute to Matplotlib. Workflow overview ------------------ +^^^^^^^^^^^^^^^^^ A brief overview of the workflow is as follows. @@ -317,7 +375,7 @@ A brief overview of the workflow is as follows. 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 @@ -336,7 +394,7 @@ 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" @@ -344,7 +402,7 @@ 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 ---------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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. @@ -355,65 +413,3 @@ generally ``main``. For more guidance, see GitHub's `pull request tutorial 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`. - -.. _new_contributors: - -First Open Source Contribution & New Contributors -================================================= - -.. _new_contributors_meeting: - -New Contributors Meeting ------------------------- - -Once a month, we host a meeting to discuss topics that interest new -contributors. Anyone can attend, present, or sit in and listen to the call. -Among our attendees are fellow new contributors, as well as maintainers, and -veteran contributors, who are keen to support onboarding of new folks and -share their experience. You can find our community calendar link at the -`Scientific Python website `_, and -you can browse previous meeting notes on `GitHub -`_. -We recommend joining the meeting to clarify any doubts, or lingering -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! - -.. _good_first_issues: - -Good first issues ------------------ - -While any contributions are welcome, we have marked some issues as -particularly suited for new contributors by the label `good first issue -`_. These -are well documented issues, that do not require a deep understanding of the -internals of Matplotlib. The issues may additionally be tagged with a -difficulty. ``Difficulty: Easy`` is suited for people with little Python -experience. ``Difficulty: Medium`` and ``Difficulty: Hard`` require more -programming experience. This could be for a variety of reasons, among them, -though not necessarily all at the same time: - -- The issue is in areas of the code base which have more interdependencies, - or legacy code. -- It has less clearly defined tasks, which require some independent - exploration, making suggestions, or follow-up discussions to clarify a good - path to resolve the issue. -- 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 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 a PR has been opened to resolve the issue. -4. If the issue is a work in progress, tag the user working on the issue, and ask to collaborate (optional). -5. Check the pull requests (i.e. :ghpull:`28476`) and filter by the issue number to make sure the issue is not in progress. -6. After steps 3 & 5 are done, and a PR does not exist, create a `draft PR `_ and follow the `pull request guidelines `_ . diff --git a/doc/devel/index.rst b/doc/devel/index.rst index f6c1bcc7ec8d..d84f309864b6 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 choose 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,29 @@ 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 should 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 From c31468d01868a95b494420dfbcee32d19d11a710 Mon Sep 17 00:00:00 2001 From: anpaulan Date: Tue, 24 Sep 2024 00:51:58 -0400 Subject: [PATCH 07/17] udpated contribution doc #28476 --- doc/devel/contribute.rst | 366 +++++++++++++++++++++------------------ doc/devel/index.rst | 6 +- 2 files changed, 197 insertions(+), 175 deletions(-) diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst index ad61c43fd348..31b3eac5e621 100644 --- a/doc/devel/contribute.rst +++ b/doc/devel/contribute.rst @@ -3,7 +3,7 @@ .. _contributing: ****************** -Contributing guide +Contribution guide ****************** @@ -27,177 +27,10 @@ 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. -.. dropdown:: Do I really have something to contribute to Matplotlib? - :open: - :icon: person-fill - - 100% yes! There are so many ways to contribute to our community. Take a look - at the following sections to learn more. - - There are a few typical new contributor profiles: - - * **You are a Matplotlib user, and you see a bug, a potential improvement, or - something that annoys you, and you can fix it.** - - You can search our issue tracker for an existing issue that describes your problem or - open a new issue to inform us of the problem you observed and discuss the best approach - to fix it. If your contributions would not be captured on GitHub (social media, - communication, educational content), you can also reach out to us on gitter_, - `Discourse `__ or attend any of our `community - meetings `__. - - * **You are not a regular Matplotlib user but a domain expert: you know about - visualization, 3D plotting, design, technical writing, statistics, or some - other field where Matplotlib could be improved.** - - Awesome -- you have a focus on a specific application and domain and can - start there. In this case, maintainers can help you figure out the best - implementation; open an issue or pull request with a starting point, and we'll - be happy to discuss technical approaches. - - If you prefer, you can use the `GitHub functionality for "draft" pull requests - `__ - and request early feedback on whatever you are working on, but you should be - aware that maintainers may not review your contribution unless it has the - "Ready to review" state on GitHub. - - * **You are new to Matplotlib, both as a user and contributor, and want to start - contributing but have yet to develop a particular interest.** - - Having some previous experience or relationship with the library can be very - helpful when making open-source contributions. It helps you understand why - things are the way they are and how they *should* be. Having first-hand - experience and context is valuable both for what you can bring to the - conversation (and given the breadth of Matplotlib's usage, there is a good - chance it is a unique context in any given conversation) and make it easier to - understand where other people are coming from. - - Understanding the entire codebase is a long-term project, and nobody expects - you to do this right away. If you are determined to get started with - Matplotlib and want to learn, going through the basic functionality, - choosing something to focus on (3d, testing, documentation, animations, etc.) - and gaining context on this area by reading the issues and pull requests - touching these subjects is a reasonable approach. - -.. _contribute_code: - -Code ----- -You want to implement a feature or fix a bug or help with maintenance - much -appreciated! Our library source code is found in: - -* Python library code: :file:`lib/` -* C-extension code: :file:`src/` -* Tests: :file:`lib/matplotlib/tests/` - -Because many people use and work on Matplotlib, we have guidelines for keeping -our code consistent and mitigating the impact of changes. - -* :ref:`coding_guidelines` -* :ref:`api_changes` -* :ref:`pr-guidelines` - -Code is contributed through pull requests, so we recommend that you start at -:ref:`how-to-pull-request` If you get stuck, please reach out on the -:ref:`contributor_incubator` - -.. _contribute_documentation: - -Documentation -------------- - -You as an end-user of Matplotlib can make a valuable contribution because you -more clearly see the potential for improvement than a core developer. For example, -you can: - -- Fix a typo -- Clarify a docstring -- Write or update an :ref:`example plot ` -- Write or update a comprehensive :ref:`tutorial ` - -Our code is documented inline in the source code files in :file:`matplotlib/lib`. -Our website structure mirrors our folder structure, meaning that a narrative -document's URL roughly corresponds to its location in our folder structure: - -.. grid:: 1 1 2 2 - - .. grid-item:: using the library - - * :file:`galleries/plot_types/` - * :file:`users/getting_started/` - * :file:`galleries/user_explain/` - * :file:`galleries/tutorials/` - * :file:`galleries/examples/` - * :file:`doc/api/` - - .. grid-item:: information about the library - - * :file:`doc/install/` - * :file:`doc/project/` - * :file:`doc/devel/` - * :file:`doc/users/resources/index.rst` - * :file:`doc/users/faq.rst` - - -Other documentation is generated from the following external sources: - -* matplotlib.org homepage: https://github.com/matplotlib/mpl-brochure-site -* cheat sheets: https://github.com/matplotlib/cheatsheets -* third party packages: https://github.com/matplotlib/mpl-third-party - -Instructions and guidelines for contributing documentation are found in: - -* :doc:`document` -* :doc:`style_guide` -* :doc:`tag_guidelines` - -Documentation is contributed through pull requests, so we recommend that you start -at :ref:`how-to-pull-request`. If that feels intimidating, we encourage you to -`open an issue`_ describing what improvements you would make. If you get stuck, -please reach out on the :ref:`contributor_incubator` - -.. _`open an issue`: https://github.com/matplotlib/matplotlib/issues/new?assignees=&labels=Documentation&projects=&template=documentation.yml&title=%5BDoc%5D%3A+ - -.. _contribute_triage: - -Triage ------- -We appreciate your help keeping the `issue tracker `_ -organized because it is our centralized location for feature requests, -bug reports, tracking major projects, and discussing priorities. Some examples of what -we mean by triage are: - -* labeling issues and pull requests -* verifying bug reports -* debugging and resolving issues -* linking to related issues, discussion, and external work - -Our triage process is discussed in detail in :ref:`bug_triaging`. - -If you have any questions about the process, please reach out on the -:ref:`contributor_incubator` - -.. _other_ways_to_contribute: - -Community ---------- -Matplotlib's community is built by its members, if you would like to help out -see our :ref:`communications-guidelines`. - -It helps us if you spread the word: reference the project from your blog -and articles or link to it from your website! - -If Matplotlib contributes to a project that leads to a scientific publication, -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. - - .. _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 @@ -243,8 +76,8 @@ suggestions. We ❤ feedback! .. _managing_issues_prs: -Work on an issue -================ +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 @@ -279,11 +112,27 @@ 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 & New Contributors +-------------------------------------- + +If this is your first open source contribution, or 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 is already claimed. +4. If the issue is claimed, tag the user working on the issue, +5. and ask to collaborate (optional). +6. Check the `pull requests (i.e. #28476) `_ and filter by the issue number to make sure the issue is not in progress. +7. After steps 3 & 4 are done, and no one is working on the issue, comment on the issue to state you are working on it. .. _how-to-pull-request: Start a pull request -==================== +-------------------- The preferred way to contribute to Matplotlib is to fork the `main repository `__ on GitHub, @@ -398,3 +247,176 @@ generally ``main``. For more guidance, see GitHub's `pull request tutorial 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`. + +Ways to contribute +================== +.. dropdown:: Do I really have something to contribute to Matplotlib? + :open: + :icon: person-fill + + 100% yes! There are so many ways to contribute to our community. Take a look + at the following sections to learn more. + + There are a few typical new contributor profiles: + + * **You are a Matplotlib user, and you see a bug, a potential improvement, or + something that annoys you, and you can fix it.** + + You can search our issue tracker for an existing issue that describes your problem or + open a new issue to inform us of the problem you observed and discuss the best approach + to fix it. If your contributions would not be captured on GitHub (social media, + communication, educational content), you can also reach out to us on gitter_, + `Discourse `__ or attend any of our `community + meetings `__. + + * **You are not a regular Matplotlib user but a domain expert: you know about + visualization, 3D plotting, design, technical writing, statistics, or some + other field where Matplotlib could be improved.** + + Awesome -- you have a focus on a specific application and domain and can + start there. In this case, maintainers can help you figure out the best + implementation; open an issue or pull request with a starting point, and we'll + be happy to discuss technical approaches. + + If you prefer, you can use the `GitHub functionality for "draft" pull requests + `__ + and request early feedback on whatever you are working on, but you should be + aware that maintainers may not review your contribution unless it has the + "Ready to review" state on GitHub. + + * **You are new to Matplotlib, both as a user and contributor, and want to start + contributing but have yet to develop a particular interest.** + + Having some previous experience or relationship with the library can be very + helpful when making open-source contributions. It helps you understand why + things are the way they are and how they *should* be. Having first-hand + experience and context is valuable both for what you can bring to the + conversation (and given the breadth of Matplotlib's usage, there is a good + chance it is a unique context in any given conversation) and make it easier to + understand where other people are coming from. + + Understanding the entire codebase is a long-term project, and nobody expects + you to do this right away. If you are determined to get started with + Matplotlib and want to learn, going through the basic functionality, + choosing something to focus on (3d, testing, documentation, animations, etc.) + and gaining context on this area by reading the issues and pull requests + touching these subjects is a reasonable approach. + +.. _contribute_code: + +Code +---- +You want to implement a feature or fix a bug or help with maintenance - much +appreciated! Our library source code is found in: + +* Python library code: :file:`lib/` +* C-extension code: :file:`src/` +* Tests: :file:`lib/matplotlib/tests/` + +Because many people use and work on Matplotlib, we have guidelines for keeping +our code consistent and mitigating the impact of changes. + +* :ref:`coding_guidelines` +* :ref:`api_changes` +* :ref:`pr-guidelines` + +Code is contributed through pull requests, so we recommend that you start at +:ref:`how-to-pull-request` If you get stuck, please reach out on the +:ref:`contributor_incubator` + +.. _contribute_documentation: + +Documentation +------------- + +You as an end-user of Matplotlib can make a valuable contribution because you +more clearly see the potential for improvement than a core developer. For example, +you can: + +- Fix a typo +- Clarify a docstring +- Write or update an :ref:`example plot ` +- Write or update a comprehensive :ref:`tutorial ` + +Our code is documented inline in the source code files in :file:`matplotlib/lib`. +Our website structure mirrors our folder structure, meaning that a narrative +document's URL roughly corresponds to its location in our folder structure: + +.. grid:: 1 1 2 2 + + .. grid-item:: using the library + + * :file:`galleries/plot_types/` + * :file:`users/getting_started/` + * :file:`galleries/user_explain/` + * :file:`galleries/tutorials/` + * :file:`galleries/examples/` + * :file:`doc/api/` + + .. grid-item:: information about the library + + * :file:`doc/install/` + * :file:`doc/project/` + * :file:`doc/devel/` + * :file:`doc/users/resources/index.rst` + * :file:`doc/users/faq.rst` + + +Other documentation is generated from the following external sources: + +* matplotlib.org homepage: https://github.com/matplotlib/mpl-brochure-site +* cheat sheets: https://github.com/matplotlib/cheatsheets +* third party packages: https://github.com/matplotlib/mpl-third-party + +Instructions and guidelines for contributing documentation are found in: + +* :doc:`document` +* :doc:`style_guide` +* :doc:`tag_guidelines` + +Documentation is contributed through pull requests, so we recommend that you start +at :ref:`how-to-pull-request`. If that feels intimidating, we encourage you to +`open an issue`_ describing what improvements you would make. If you get stuck, +please reach out on the :ref:`contributor_incubator` + +.. _`open an issue`: https://github.com/matplotlib/matplotlib/issues/new?assignees=&labels=Documentation&projects=&template=documentation.yml&title=%5BDoc%5D%3A+ + +.. _contribute_triage: + +Triage +------ +We appreciate your help keeping the `issue tracker `_ +organized because it is our centralized location for feature requests, +bug reports, tracking major projects, and discussing priorities. Some examples of what +we mean by triage are: + +* labeling issues and pull requests +* verifying bug reports +* debugging and resolving issues +* linking to related issues, discussion, and external work + +Our triage process is discussed in detail in :ref:`bug_triaging`. + +If you have any questions about the process, please reach out on the +:ref:`contributor_incubator` + +.. _other_ways_to_contribute: + +Community +--------- +Matplotlib's community is built by its members, if you would like to help out +see our :ref:`communications-guidelines`. + +It helps us if you spread the word: reference the project from your blog +and articles or link to it from your website! + +If Matplotlib contributes to a project that leads to a scientific publication, +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. + + + + + diff --git a/doc/devel/index.rst b/doc/devel/index.rst index fedf9b76e875..ff2e5b9feb89 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -71,7 +71,7 @@ Since Matplotlib is an open source project with limited resources, we encourage to also :ref:`participate ` in fixing bugs and implementing new features. -Contributing guide +Contribution guide ================== We welcome you to get more involved with the Matplotlib project! If you are new @@ -101,12 +101,12 @@ to contributing, we recommend that you first read our .. grid-item:: - :octicon:`git-pull-request;1em;sd-text-info` :ref:`How do I work on an issue? ` + :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? ` - + .. grid-item:: .. grid:: 1 From bd9f5fe000244815abeb0a59304d2679a4c9d5fb Mon Sep 17 00:00:00 2001 From: anpaulan Date: Tue, 24 Sep 2024 01:03:27 -0400 Subject: [PATCH 08/17] udpated contribution doc #28476 --- doc/devel/contribute.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst index 31b3eac5e621..45c0f857e64d 100644 --- a/doc/devel/contribute.rst +++ b/doc/devel/contribute.rst @@ -124,10 +124,9 @@ 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 is already claimed. -4. If the issue is claimed, tag the user working on the issue, -5. and ask to collaborate (optional). -6. Check the `pull requests (i.e. #28476) `_ and filter by the issue number to make sure the issue is not in progress. -7. After steps 3 & 4 are done, and no one is working on the issue, comment on the issue to state you are working on it. +4. If the issue is claimed, tag the user working on the issue, and ask to collaborate (optional). +5. Check the `pull requests (i.e. #28476) `_ and filter by the issue number to make sure the issue is not in progress. +6. After steps 3 & 4 are done, and no one is working on the issue, comment on the issue to state you are working on it. .. _how-to-pull-request: @@ -301,7 +300,7 @@ Ways to contribute choosing something to focus on (3d, testing, documentation, animations, etc.) and gaining context on this area by reading the issues and pull requests touching these subjects is a reasonable approach. - + .. _contribute_code: Code From e7350586eec9f2d77ec3811794936ed1c9189d54 Mon Sep 17 00:00:00 2001 From: anpaulan Date: Tue, 24 Sep 2024 18:19:39 -0400 Subject: [PATCH 09/17] used pre-install to fix failed checks --- doc/devel/contribute.rst | 7 +------ doc/devel/index.rst | 4 ++-- 2 files changed, 3 insertions(+), 8 deletions(-) diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst index 45c0f857e64d..7ebf65890b0e 100644 --- a/doc/devel/contribute.rst +++ b/doc/devel/contribute.rst @@ -118,7 +118,7 @@ First Contributions & New Contributors -------------------------------------- If this is your first open source contribution, or first time contributing to Matplotlib, -and you need help or guidance finding a good first issue, look no further. This section will +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 `_. @@ -414,8 +414,3 @@ 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. - - - - - diff --git a/doc/devel/index.rst b/doc/devel/index.rst index ff2e5b9feb89..f6c1bcc7ec8d 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -71,7 +71,7 @@ Since Matplotlib is an open source project with limited resources, we encourage to also :ref:`participate ` in fixing bugs and implementing new features. -Contribution guide +Contribution guide ================== We welcome you to get more involved with the Matplotlib project! If you are new @@ -106,7 +106,7 @@ to contributing, we recommend that you first read our .. grid-item:: :octicon:`codespaces;1em;sd-text-info` :ref:`How do I start a pull request? ` - + .. grid-item:: .. grid:: 1 From f66073ed76f398b539c59a96624d46f9a24fa76e Mon Sep 17 00:00:00 2001 From: anpaulan Date: Fri, 27 Sep 2024 23:55:10 -0400 Subject: [PATCH 10/17] reorganized contribution doc --- doc/devel/contribute.rst | 433 ++++++++++++++++++++------------------- 1 file changed, 218 insertions(+), 215 deletions(-) diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst index 7ebf65890b0e..6c9e57f81fd3 100644 --- a/doc/devel/contribute.rst +++ b/doc/devel/contribute.rst @@ -27,10 +27,178 @@ 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 + + 100% yes! There are so many ways to contribute to our community. Take a look + at the following sections to learn more. + + There are a few typical new contributor profiles: + + * **You are a Matplotlib user, and you see a bug, a potential improvement, or + something that annoys you, and you can fix it.** + + You can search our issue tracker for an existing issue that describes your problem or + open a new issue to inform us of the problem you observed and discuss the best approach + to fix it. If your contributions would not be captured on GitHub (social media, + communication, educational content), you can also reach out to us on gitter_, + `Discourse `__ or attend any of our `community + meetings `__. + + * **You are not a regular Matplotlib user but a domain expert: you know about + visualization, 3D plotting, design, technical writing, statistics, or some + other field where Matplotlib could be improved.** + + Awesome -- you have a focus on a specific application and domain and can + start there. In this case, maintainers can help you figure out the best + implementation; open an issue or pull request with a starting point, and we'll + be happy to discuss technical approaches. + + If you prefer, you can use the `GitHub functionality for "draft" pull requests + `__ + and request early feedback on whatever you are working on, but you should be + aware that maintainers may not review your contribution unless it has the + "Ready to review" state on GitHub. + + * **You are new to Matplotlib, both as a user and contributor, and want to start + contributing but have yet to develop a particular interest.** + + Having some previous experience or relationship with the library can be very + helpful when making open-source contributions. It helps you understand why + things are the way they are and how they *should* be. Having first-hand + experience and context is valuable both for what you can bring to the + conversation (and given the breadth of Matplotlib's usage, there is a good + chance it is a unique context in any given conversation) and make it easier to + understand where other people are coming from. + + Understanding the entire codebase is a long-term project, and nobody expects + you to do this right away. If you are determined to get started with + Matplotlib and want to learn, going through the basic functionality, + choosing something to focus on (3d, testing, documentation, animations, etc.) + and gaining context on this area by reading the issues and pull requests + touching these subjects is a reasonable approach. + +.. _contribute_code: + +Code +---- +You want to implement a feature or fix a bug or help with maintenance - much +appreciated! Our library source code is found in: + +* Python library code: :file:`lib/` +* C-extension code: :file:`src/` +* Tests: :file:`lib/matplotlib/tests/` + +Because many people use and work on Matplotlib, we have guidelines for keeping +our code consistent and mitigating the impact of changes. + +* :ref:`coding_guidelines` +* :ref:`api_changes` +* :ref:`pr-guidelines` + +Code is contributed through pull requests, so we recommend that you start at +:ref:`how-to-pull-request` If you get stuck, please reach out on the +:ref:`contributor_incubator` + +.. _contribute_documentation: + +Documentation +------------- + +You as an end-user of Matplotlib can make a valuable contribution because you +more clearly see the potential for improvement than a core developer. For example, +you can: + +- Fix a typo +- Clarify a docstring +- Write or update an :ref:`example plot ` +- Write or update a comprehensive :ref:`tutorial ` + +Our code is documented inline in the source code files in :file:`matplotlib/lib`. +Our website structure mirrors our folder structure, meaning that a narrative +document's URL roughly corresponds to its location in our folder structure: + +.. grid:: 1 1 2 2 + + .. grid-item:: using the library + + * :file:`galleries/plot_types/` + * :file:`users/getting_started/` + * :file:`galleries/user_explain/` + * :file:`galleries/tutorials/` + * :file:`galleries/examples/` + * :file:`doc/api/` + + .. grid-item:: information about the library + + * :file:`doc/install/` + * :file:`doc/project/` + * :file:`doc/devel/` + * :file:`doc/users/resources/index.rst` + * :file:`doc/users/faq.rst` + + +Other documentation is generated from the following external sources: + +* matplotlib.org homepage: https://github.com/matplotlib/mpl-brochure-site +* cheat sheets: https://github.com/matplotlib/cheatsheets +* third party packages: https://github.com/matplotlib/mpl-third-party + +Instructions and guidelines for contributing documentation are found in: + +* :doc:`document` +* :doc:`style_guide` +* :doc:`tag_guidelines` + +Documentation is contributed through pull requests, so we recommend that you start +at :ref:`how-to-pull-request`. If that feels intimidating, we encourage you to +`open an issue`_ describing what improvements you would make. If you get stuck, +please reach out on the :ref:`contributor_incubator` + +.. _`open an issue`: https://github.com/matplotlib/matplotlib/issues/new?assignees=&labels=Documentation&projects=&template=documentation.yml&title=%5BDoc%5D%3A+ + +.. _contribute_triage: + +Triage +------ +We appreciate your help keeping the `issue tracker `_ +organized because it is our centralized location for feature requests, +bug reports, tracking major projects, and discussing priorities. Some examples of what +we mean by triage are: + +* labeling issues and pull requests +* verifying bug reports +* debugging and resolving issues +* linking to related issues, discussion, and external work + +Our triage process is discussed in detail in :ref:`bug_triaging`. + +If you have any questions about the process, please reach out on the +:ref:`contributor_incubator` + +.. _other_ways_to_contribute: + +Community +--------- +Matplotlib's community is built by its members, if you would like to help out +see our :ref:`communications-guidelines`. + +It helps us if you spread the word: reference the project from your blog +and articles or link to it from your website! + +If Matplotlib contributes to a project that leads to a scientific publication, +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. + .. _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 @@ -55,25 +223,6 @@ To join, please go to our public community_ channel, and ask to be added to .. _gitter: https://gitter.im/matplotlib/matplotlib .. _community: https://gitter.im/matplotlib/community - -.. _new_contributors: - -New Contributors Meeting ------------------------- - -Once a month, we host a meeting to discuss topics that interest new -contributors. Anyone can attend, present, or sit in and listen to the call. -Among our attendees are fellow new contributors, as well as maintainers, and -veteran contributors, who are keen to support onboarding of new folks and -share their experience. You can find our community calendar link at the -`Scientific Python website `_, and -you can browse previous meeting notes on `GitHub -`_. -We recommend joining the meeting to clarify any doubts, or lingering -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: Choose an issue @@ -89,45 +238,6 @@ 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. -.. _good_first_issues: - -Good first issues ------------------ - -While any contributions are welcome, we have marked some issues as -particularly suited for new contributors by the label `good first issue -`_. These -are well documented issues, that do not require a deep understanding of the -internals of Matplotlib. The issues may additionally be tagged with a -difficulty. ``Difficulty: Easy`` is suited for people with little Python -experience. ``Difficulty: Medium`` and ``Difficulty: Hard`` require more -programming experience. This could be for a variety of reasons, among them, -though not necessarily all at the same time: - -- The issue is in areas of the code base which have more interdependencies, - or legacy code. -- It has less clearly defined tasks, which require some independent - exploration, making suggestions, or follow-up discussions to clarify a good - path to resolve the issue. -- It involves Python features such as decorators and context managers, which - have subtleties due to our implementation decisions. - -.. _first_contribution: - -First Contributions & New Contributors --------------------------------------- - -If this is your first open source contribution, or 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 is already claimed. -4. If the issue is claimed, tag the user working on the issue, and ask to collaborate (optional). -5. Check the `pull requests (i.e. #28476) `_ and filter by the issue number to make sure the issue is not in progress. -6. After steps 3 & 4 are done, and no one is working on the issue, comment on the issue to state you are working on it. - .. _how-to-pull-request: Start a pull request @@ -233,7 +343,6 @@ 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 --------------------------------- @@ -247,170 +356,64 @@ 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`. -Ways to contribute -================== -.. dropdown:: Do I really have something to contribute to Matplotlib? - :open: - :icon: person-fill - - 100% yes! There are so many ways to contribute to our community. Take a look - at the following sections to learn more. - - There are a few typical new contributor profiles: - - * **You are a Matplotlib user, and you see a bug, a potential improvement, or - something that annoys you, and you can fix it.** - - You can search our issue tracker for an existing issue that describes your problem or - open a new issue to inform us of the problem you observed and discuss the best approach - to fix it. If your contributions would not be captured on GitHub (social media, - communication, educational content), you can also reach out to us on gitter_, - `Discourse `__ or attend any of our `community - meetings `__. - - * **You are not a regular Matplotlib user but a domain expert: you know about - visualization, 3D plotting, design, technical writing, statistics, or some - other field where Matplotlib could be improved.** - - Awesome -- you have a focus on a specific application and domain and can - start there. In this case, maintainers can help you figure out the best - implementation; open an issue or pull request with a starting point, and we'll - be happy to discuss technical approaches. - - If you prefer, you can use the `GitHub functionality for "draft" pull requests - `__ - and request early feedback on whatever you are working on, but you should be - aware that maintainers may not review your contribution unless it has the - "Ready to review" state on GitHub. - - * **You are new to Matplotlib, both as a user and contributor, and want to start - contributing but have yet to develop a particular interest.** - - Having some previous experience or relationship with the library can be very - helpful when making open-source contributions. It helps you understand why - things are the way they are and how they *should* be. Having first-hand - experience and context is valuable both for what you can bring to the - conversation (and given the breadth of Matplotlib's usage, there is a good - chance it is a unique context in any given conversation) and make it easier to - understand where other people are coming from. - - Understanding the entire codebase is a long-term project, and nobody expects - you to do this right away. If you are determined to get started with - Matplotlib and want to learn, going through the basic functionality, - choosing something to focus on (3d, testing, documentation, animations, etc.) - and gaining context on this area by reading the issues and pull requests - touching these subjects is a reasonable approach. - -.. _contribute_code: - -Code ----- -You want to implement a feature or fix a bug or help with maintenance - much -appreciated! Our library source code is found in: - -* Python library code: :file:`lib/` -* C-extension code: :file:`src/` -* Tests: :file:`lib/matplotlib/tests/` - -Because many people use and work on Matplotlib, we have guidelines for keeping -our code consistent and mitigating the impact of changes. - -* :ref:`coding_guidelines` -* :ref:`api_changes` -* :ref:`pr-guidelines` - -Code is contributed through pull requests, so we recommend that you start at -:ref:`how-to-pull-request` If you get stuck, please reach out on the -:ref:`contributor_incubator` - -.. _contribute_documentation: - -Documentation -------------- - -You as an end-user of Matplotlib can make a valuable contribution because you -more clearly see the potential for improvement than a core developer. For example, -you can: - -- Fix a typo -- Clarify a docstring -- Write or update an :ref:`example plot ` -- Write or update a comprehensive :ref:`tutorial ` - -Our code is documented inline in the source code files in :file:`matplotlib/lib`. -Our website structure mirrors our folder structure, meaning that a narrative -document's URL roughly corresponds to its location in our folder structure: - -.. grid:: 1 1 2 2 - - .. grid-item:: using the library - - * :file:`galleries/plot_types/` - * :file:`users/getting_started/` - * :file:`galleries/user_explain/` - * :file:`galleries/tutorials/` - * :file:`galleries/examples/` - * :file:`doc/api/` - - .. grid-item:: information about the library - - * :file:`doc/install/` - * :file:`doc/project/` - * :file:`doc/devel/` - * :file:`doc/users/resources/index.rst` - * :file:`doc/users/faq.rst` - - -Other documentation is generated from the following external sources: - -* matplotlib.org homepage: https://github.com/matplotlib/mpl-brochure-site -* cheat sheets: https://github.com/matplotlib/cheatsheets -* third party packages: https://github.com/matplotlib/mpl-third-party - -Instructions and guidelines for contributing documentation are found in: - -* :doc:`document` -* :doc:`style_guide` -* :doc:`tag_guidelines` +.. _new_contributors: -Documentation is contributed through pull requests, so we recommend that you start -at :ref:`how-to-pull-request`. If that feels intimidating, we encourage you to -`open an issue`_ describing what improvements you would make. If you get stuck, -please reach out on the :ref:`contributor_incubator` +First Open Source Contribution & New Contributors +================================================= -.. _`open an issue`: https://github.com/matplotlib/matplotlib/issues/new?assignees=&labels=Documentation&projects=&template=documentation.yml&title=%5BDoc%5D%3A+ +.. _new_contributors_meeting: -.. _contribute_triage: +New Contributors Meeting +------------------------ -Triage ------- -We appreciate your help keeping the `issue tracker `_ -organized because it is our centralized location for feature requests, -bug reports, tracking major projects, and discussing priorities. Some examples of what -we mean by triage are: +Once a month, we host a meeting to discuss topics that interest new +contributors. Anyone can attend, present, or sit in and listen to the call. +Among our attendees are fellow new contributors, as well as maintainers, and +veteran contributors, who are keen to support onboarding of new folks and +share their experience. You can find our community calendar link at the +`Scientific Python website `_, and +you can browse previous meeting notes on `GitHub +`_. +We recommend joining the meeting to clarify any doubts, or lingering +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! -* labeling issues and pull requests -* verifying bug reports -* debugging and resolving issues -* linking to related issues, discussion, and external work +.. _good_first_issues: -Our triage process is discussed in detail in :ref:`bug_triaging`. +Good first issues +----------------- -If you have any questions about the process, please reach out on the -:ref:`contributor_incubator` +While any contributions are welcome, we have marked some issues as +particularly suited for new contributors by the label `good first issue +`_. These +are well documented issues, that do not require a deep understanding of the +internals of Matplotlib. The issues may additionally be tagged with a +difficulty. ``Difficulty: Easy`` is suited for people with little Python +experience. ``Difficulty: Medium`` and ``Difficulty: Hard`` require more +programming experience. This could be for a variety of reasons, among them, +though not necessarily all at the same time: -.. _other_ways_to_contribute: +- The issue is in areas of the code base which have more interdependencies, + or legacy code. +- It has less clearly defined tasks, which require some independent + exploration, making suggestions, or follow-up discussions to clarify a good + path to resolve the issue. +- It involves Python features such as decorators and context managers, which + have subtleties due to our implementation decisions. -Community ---------- -Matplotlib's community is built by its members, if you would like to help out -see our :ref:`communications-guidelines`. +.. _first_contribution: -It helps us if you spread the word: reference the project from your blog -and articles or link to it from your website! +First Contributions +------------------- -If Matplotlib contributes to a project that leads to a scientific publication, -please cite us following the :doc:`/project/citing` guidelines. +If this is your first open source contribution, or 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. -If you have developed an extension to Matplotlib, please consider adding it to our -`third party package `_ list. +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 a PR has been opened to resolve the issue. +4. If the issue is a work in progress, tag the user working on the issue, and ask to collaborate (optional). +5. Check the pull requests (i.e. :ghpull:`28476`) and filter by the issue number to make sure the issue is not in progress. +6. After steps 3 & 5 are done, and a PR does not exist, open a 'draft (incomeplete) PR '_. From d4afdee2dc5848d0848ee32fe4faf0a1c0662afd Mon Sep 17 00:00:00 2001 From: anpaulan Date: Wed, 2 Oct 2024 14:02:40 -0400 Subject: [PATCH 11/17] updated text and embdedded links render properly --- doc/devel/contribute.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst index 6c9e57f81fd3..851bf8d5b610 100644 --- a/doc/devel/contribute.rst +++ b/doc/devel/contribute.rst @@ -416,4 +416,4 @@ guide you through each step. 3. Click on an issue you would like to work on, and check to see if the issue a PR has been opened to resolve the issue. 4. If the issue is a work in progress, tag the user working on the issue, and ask to collaborate (optional). 5. Check the pull requests (i.e. :ghpull:`28476`) and filter by the issue number to make sure the issue is not in progress. -6. After steps 3 & 5 are done, and a PR does not exist, open a 'draft (incomeplete) PR '_. +6. After steps 3 & 5 are done, and a PR does not exist, create a `draft PR `_ and follow the `pull request guidelines `_ . From 38ee3bd31a8803c7468ce47373432f98830a2691 Mon Sep 17 00:00:00 2001 From: anpaulan Date: Sat, 12 Oct 2024 10:22:03 -0400 Subject: [PATCH 12/17] updated guide structure and index cards --- doc/devel/contribute.rst | 162 +++++++++++++++++++-------------------- doc/devel/index.rst | 44 ++++++----- 2 files changed, 102 insertions(+), 104 deletions(-) diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst index 851bf8d5b610..7ac9a95cda99 100644 --- a/doc/devel/contribute.rst +++ b/doc/devel/contribute.rst @@ -17,16 +17,6 @@ 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? @@ -195,20 +185,88 @@ 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: + +New Contributors +================ + +.. _new_contributors_meeting: + +New Contributors Meeting +------------------------ + +Once a month, we host a meeting to discuss topics that interest new +contributors. Anyone can attend, present, or sit in and listen to the call. +Among our attendees are fellow new contributors, as well as maintainers, and +veteran contributors, who are keen to support onboarding of new folks and +share their experience. You can find our community calendar link at the +`Scientific Python website `_, and +you can browse previous meeting notes on `GitHub +`_. +We recommend joining the meeting to clarify any doubts, or lingering +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! + +.. _good_first_issues: + +Good first issues +----------------- + +While any contributions are welcome, we have marked some issues as +particularly suited for new contributors by the label `good first issue +`_. These +are well documented issues, that do not require a deep understanding of the +internals of Matplotlib. The issues may additionally be tagged with a +difficulty. ``Difficulty: Easy`` is suited for people with little Python +experience. ``Difficulty: Medium`` and ``Difficulty: Hard`` require more +programming experience. This could be for a variety of reasons, among them, +though not necessarily all at the same time: + +- The issue is in areas of the code base which have more interdependencies, + or legacy code. +- It has less clearly defined tasks, which require some independent + exploration, making suggestions, or follow-up discussions to clarify a good + path to resolve the issue. +- 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 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 a PR has been opened to resolve the issue. +4. If the issue is a work in progress, tag the user working on the issue, and ask to collaborate (optional). +5. Check the pull requests (i.e. :ghpull:`28476`) and filter by the issue number to make sure the issue is not in progress. +6. After steps 3 & 5 are done, and a PR does not exist, create a `draft PR `_ and follow the `pull request guidelines `_ . + +.. _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. + .. _get_connected: -Get connected -============= +Get connected: Contributor incubator +------------------------------------ + 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 @@ -252,7 +310,7 @@ in-browser development environment that comes with the appropriate setup to contribute to Matplotlib. Workflow overview ------------------ +^^^^^^^^^^^^^^^^^ A brief overview of the workflow is as follows. @@ -317,7 +375,7 @@ A brief overview of the workflow is as follows. 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 @@ -336,7 +394,7 @@ 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" @@ -344,7 +402,7 @@ 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 ---------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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. @@ -355,65 +413,3 @@ generally ``main``. For more guidance, see GitHub's `pull request tutorial 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`. - -.. _new_contributors: - -First Open Source Contribution & New Contributors -================================================= - -.. _new_contributors_meeting: - -New Contributors Meeting ------------------------- - -Once a month, we host a meeting to discuss topics that interest new -contributors. Anyone can attend, present, or sit in and listen to the call. -Among our attendees are fellow new contributors, as well as maintainers, and -veteran contributors, who are keen to support onboarding of new folks and -share their experience. You can find our community calendar link at the -`Scientific Python website `_, and -you can browse previous meeting notes on `GitHub -`_. -We recommend joining the meeting to clarify any doubts, or lingering -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! - -.. _good_first_issues: - -Good first issues ------------------ - -While any contributions are welcome, we have marked some issues as -particularly suited for new contributors by the label `good first issue -`_. These -are well documented issues, that do not require a deep understanding of the -internals of Matplotlib. The issues may additionally be tagged with a -difficulty. ``Difficulty: Easy`` is suited for people with little Python -experience. ``Difficulty: Medium`` and ``Difficulty: Hard`` require more -programming experience. This could be for a variety of reasons, among them, -though not necessarily all at the same time: - -- The issue is in areas of the code base which have more interdependencies, - or legacy code. -- It has less clearly defined tasks, which require some independent - exploration, making suggestions, or follow-up discussions to clarify a good - path to resolve the issue. -- 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 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 a PR has been opened to resolve the issue. -4. If the issue is a work in progress, tag the user working on the issue, and ask to collaborate (optional). -5. Check the pull requests (i.e. :ghpull:`28476`) and filter by the issue number to make sure the issue is not in progress. -6. After steps 3 & 5 are done, and a PR does not exist, create a `draft PR `_ and follow the `pull request guidelines `_ . diff --git a/doc/devel/index.rst b/doc/devel/index.rst index f6c1bcc7ec8d..d84f309864b6 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 choose 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,29 @@ 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 should 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 From 0fed126bcd4b16f7ad9fc24b04419de76ea729a9 Mon Sep 17 00:00:00 2001 From: anpaulan Date: Sun, 20 Oct 2024 12:15:34 -0400 Subject: [PATCH 13/17] undid the improper commit --- .github/PULL_REQUEST_TEMPLATE.md | 5 ++- doc/devel/contribute.rst | 61 +++++++++++++++++++++++--------- 2 files changed, 48 insertions(+), 18 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 7f17a80dc4b6..85124abb9f27 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -8,7 +8,9 @@ out the development guide https://matplotlib.org/devdocs/devel/index.html (Why is this change required? What problem does it solve?) and link to relevant issues and PRs. -Also please summarize the changes in the title, for example "Raise ValueError on +Additionally, please explain in 1-4 sentences your implementation choices. + +Finally, 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". --> @@ -18,6 +20,7 @@ issue #8576". - [ ] "closes #0000" is in the body of the PR description to [link the related issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) +- [ ] explained implementation choices in the summary - [ ] new and changed code is [tested](https://matplotlib.org/devdocs/devel/testing.html) - [ ] *Plotting related* features are demonstrated in an [example](https://matplotlib.org/devdocs/devel/document.html#write-examples-and-tutorials) - [ ] *New Features* and *API Changes* are noted with a [directive and release note](https://matplotlib.org/devdocs/devel/api_changes.html#announce-changes-deprecations-and-new-features) diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst index 7ac9a95cda99..c7080e899682 100644 --- a/doc/devel/contribute.rst +++ b/doc/devel/contribute.rst @@ -98,7 +98,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: @@ -208,6 +208,25 @@ 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! +.. _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. + +.. _gitter: https://gitter.im/matplotlib/matplotlib +.. _community: https://gitter.im/matplotlib/community + .. _good_first_issues: Good first issues @@ -242,10 +261,27 @@ 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 a PR has been opened to resolve the issue. -4. If the issue is a work in progress, tag the user working on the issue, and ask to collaborate (optional). +3. Click on an issue you would like to work on, and check to see if the issue has a PR opened to resolve the issue. +4. 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?" 5. Check the pull requests (i.e. :ghpull:`28476`) and filter by the issue number to make sure the issue is not in progress. -6. After steps 3 & 5 are done, and a PR does not exist, create a `draft PR `_ and follow the `pull request guidelines `_ . +6. If the issue has a PR (is in progress), tag the user working on the issue, and ask to collaborate (optional). +7. After steps 3 & 5 are done, and a PR does not exist, create a `draft PR `_ and follow the `pull request guidelines `_ . +8. Please familiarize yourself with the PR Checklist (see below), and ensure you understand/are able to complete the checklist when it comes time to your PR. Additional information can be found in the `pull request guidelines `_. + + .. note:: + `PR Checklist `_ + + Please mark any checkboxes that do not apply to this PR as [N/A]. + + - [ ] "closes #0000" is in the body of the PR description to `link the related issue `_ + + - [ ] new and changed code is `tested `_ + + - [ ] *Plotting related* features are demonstrated in an `example `_ + + - [ ] *New Features* and *API Changes* are noted with a `directive and release note `_ + + - [ ] Documentation complies with `general `_ and `docstring `_ guidelines .. _start-contributing: @@ -259,24 +295,15 @@ of the code-base to understand what is going on. .. _get_connected: -Get connected: Contributor incubator +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. - -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. +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 From 5fc8affe60908455daec2ccb8cf23859e98048fa Mon Sep 17 00:00:00 2001 From: anpaulan Date: Sun, 20 Oct 2024 13:07:45 -0400 Subject: [PATCH 14/17] additional grammar edits & updated checklist in contribute.rst --- .github/PULL_REQUEST_TEMPLATE.md | 4 ++-- doc/devel/contribute.rst | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 85124abb9f27..e9631c2d569f 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -11,7 +11,7 @@ issues and PRs. Additionally, please explain in 1-4 sentences your implementation choices. Finally, 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 +non-numeric input to set_xlim" andgu avoid non-descriptive titles such as "Addresses issue #8576". --> @@ -20,7 +20,7 @@ issue #8576". - [ ] "closes #0000" is in the body of the PR description to [link the related issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) -- [ ] explained implementation choices in the summary +- [ ] explain implementation choices in the summary - [ ] new and changed code is [tested](https://matplotlib.org/devdocs/devel/testing.html) - [ ] *Plotting related* features are demonstrated in an [example](https://matplotlib.org/devdocs/devel/document.html#write-examples-and-tutorials) - [ ] *New Features* and *API Changes* are noted with a [directive and release note](https://matplotlib.org/devdocs/devel/api_changes.html#announce-changes-deprecations-and-new-features) diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst index c7080e899682..8a3e5c6066ff 100644 --- a/doc/devel/contribute.rst +++ b/doc/devel/contribute.rst @@ -275,6 +275,8 @@ guide you through each step. - [ ] "closes #0000" is in the body of the PR description to `link the related issue `_ + - [ ] explain implementation choices in the summary + - [ ] new and changed code is `tested `_ - [ ] *Plotting related* features are demonstrated in an `example `_ From 842e2f48dad996de8b8a67b1598c28111c7cff81 Mon Sep 17 00:00:00 2001 From: anpaulan Date: Sat, 26 Oct 2024 14:06:50 -0400 Subject: [PATCH 15/17] updated structure, used literal include, updated content --- .github/PULL_REQUEST_TEMPLATE.md | 13 +++--- doc/devel/contribute.rst | 78 ++++++++++++++------------------ doc/devel/index.rst | 5 +- 3 files changed, 43 insertions(+), 53 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index e9631c2d569f..c3e14777d1ce 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -4,14 +4,14 @@ out the development guide https://matplotlib.org/devdocs/devel/index.html --> ## PR summary - @@ -20,7 +20,6 @@ issue #8576". - [ ] "closes #0000" is in the body of the PR description to [link the related issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) -- [ ] explain implementation choices in the summary - [ ] new and changed code is [tested](https://matplotlib.org/devdocs/devel/testing.html) - [ ] *Plotting related* features are demonstrated in an [example](https://matplotlib.org/devdocs/devel/document.html#write-examples-and-tutorials) - [ ] *New Features* and *API Changes* are noted with a [directive and release note](https://matplotlib.org/devdocs/devel/api_changes.html#announce-changes-deprecations-and-new-features) diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst index 8a3e5c6066ff..ad5927ca9246 100644 --- a/doc/devel/contribute.rst +++ b/doc/devel/contribute.rst @@ -3,10 +3,8 @@ .. _contributing: ****************** -Contribution guide +Contributing guide ****************** - - You've discovered a bug or something else you want to change in Matplotlib — excellent! @@ -187,12 +185,22 @@ If you have developed an extension to Matplotlib, please consider adding it to o .. _new_contributors: -New Contributors +New contributors ================ +.. _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. + .. _new_contributors_meeting: -New Contributors Meeting +New contributors meeting ------------------------ Once a month, we host a meeting to discuss topics that interest new @@ -252,53 +260,37 @@ though not necessarily all at the same time: .. _first_contribution: -First Contributions +First contributions ------------------- -If this is your first open source contribution, or first time contributing to Matplotlib, +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 PR opened to resolve the issue. -4. 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?" -5. Check the pull requests (i.e. :ghpull:`28476`) and filter by the issue number to make sure the issue is not in progress. -6. If the issue has a PR (is in progress), tag the user working on the issue, and ask to collaborate (optional). -7. After steps 3 & 5 are done, and a PR does not exist, create a `draft PR `_ and follow the `pull request guidelines `_ . -8. Please familiarize yourself with the PR Checklist (see below), and ensure you understand/are able to complete the checklist when it comes time to your PR. Additional information can be found in the `pull request guidelines `_. - - .. note:: - `PR Checklist `_ - - Please mark any checkboxes that do not apply to this PR as [N/A]. +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 the pull requests (e.g., :ghpull:`28476`) and filter by the issue number to make sure the issue is not in progress: - - [ ] "closes #0000" is in the body of the PR description to `link the related issue `_ + * 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 it comes time for your pull request. + Additional information can be found in the `pull request guidelines `_. - - [ ] explain implementation choices in the summary +.. note:: - - [ ] new and changed code is `tested `_ + `Pull request template `_ - - [ ] *Plotting related* features are demonstrated in an `example `_ - - - [ ] *New Features* and *API Changes* are noted with a `directive and release note `_ - - - [ ] Documentation complies with `general `_ and `docstring `_ guidelines - -.. _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. + .. literalinclude:: ../../.github/PULL_REQUEST_TEMPLATE.md + :language: markdown .. _get_connected: -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 @@ -313,7 +305,7 @@ chat room and for community questions reach out at 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 @@ -328,7 +320,7 @@ unresponsive, feel free to open a new PR referencing the old one. .. _how-to-pull-request: Start a pull request --------------------- +==================== The preferred way to contribute to Matplotlib is to fork the `main repository `__ on GitHub, @@ -339,7 +331,7 @@ in-browser development environment that comes with the appropriate setup to contribute to Matplotlib. Workflow overview -^^^^^^^^^^^^^^^^^ +----------------- A brief overview of the workflow is as follows. @@ -397,7 +389,7 @@ 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:: diff --git a/doc/devel/index.rst b/doc/devel/index.rst index d84f309864b6..4c71027c75ba 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -71,7 +71,7 @@ Since Matplotlib is an open source project with limited resources, we encourage to also :ref:`participate ` in fixing bugs and implementing new features. -Contribution guide +Contributing guide ================== We welcome you to get more involved with the Matplotlib project! If you are new @@ -134,7 +134,7 @@ to contributing, we recommend that you first read our .. grid-item:: - :octicon:`question;1em;sd-text-info` :ref:`Where should I ask questions? ` + :octicon:`question;1em;sd-text-info` :ref:`Where do I ask questions? ` .. grid-item:: @@ -145,7 +145,6 @@ to contributing, we recommend that you first read our :octicon:`codespaces;1em;sd-text-info` :ref:`How do I start a pull request? ` - .. _development_environment: Development workflow From 0eb5ae54e358dd65f68ee2161e7cdb0160069a0d Mon Sep 17 00:00:00 2001 From: anpaulan Date: Sun, 27 Oct 2024 18:43:47 -0400 Subject: [PATCH 16/17] minor tweaks to content and dropdown inplace of note --- .github/PULL_REQUEST_TEMPLATE.md | 4 ++-- doc/devel/contribute.rst | 12 +++--------- 2 files changed, 5 insertions(+), 11 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index c3e14777d1ce..e857416b13d8 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -4,9 +4,9 @@ out the development guide https://matplotlib.org/devdocs/devel/index.html --> ## PR summary -