From bd3c10f9e109b0314f3f9c65c2060980ff96a846 Mon Sep 17 00:00:00 2001 From: melissawm Date: Tue, 14 Feb 2023 12:35:23 -0300 Subject: [PATCH 1/7] DOC: Add section on how to start contributing --- doc/devel/contributing.rst | 64 ++++++++++++++++++++++++++++++++++---- 1 file changed, 58 insertions(+), 6 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 6026c7b4d443..52f2d349cabd 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -36,16 +36,15 @@ Contributor incubator --------------------- The incubator is our non-public communication channel for new contributors. It -is a private gitter room moderated by core Matplotlib developers where you can +is a private gitter_ room moderated by core Matplotlib developers where you can get guidance and support for your first few PRs. It's a place 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 "pre-review" on your PR. -To join, please go to our public `gitter -`_ community channel, and ask to be -added to '#incubator'. One of our core developers will see your message and will +To join, please go to our public gitter_ community channel, and ask to be added +added to `#incubator`. One of our core developers will see your message and will add you. New Contributors meeting @@ -62,8 +61,7 @@ you can browse previous meeting notes on `GitHub new_contributor_meeting>`_. 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 @noatamir on `gitter -`_ for any clarifications or +GitHub handles 😉. You can reach out to us on gitter_ for any clarifications or suggestions. We <3 feedback! .. _new_contributors: @@ -99,6 +97,58 @@ 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. +.. _start-contributing: + +Is there a recommended way to get started with contributions? +------------------------------------------------------------- + +There is no pre-defined pathway for new contributors, but in practical terms - +looking at subsets of the Matplotlib source code is reasonable, as is looking at +existing issue and pull request discussions. You can learn a lot from the +observations and corrections that come up in code review, for example. + +There are a few very 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.** + + This is how a lot of people approach open-source development. 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).** + + In this case, even if you need help with programming skills or don't know + where to start, 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; you can open a (draft or not) pull request with a starting + point, and we'll be happy to discuss technical approaches. + +* **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 and + choosing something to focus on (3d, testing, documentation, animations, etc.) + and building your way up from issues and pull requests touching these subjects + is a reasonable approach. + + .. _submitting-a-bug-report: Submitting a bug report @@ -543,3 +593,5 @@ example code you can load it into a file handle with:: import matplotlib.cbook as cbook fh = cbook.get_sample_data('mydata.dat') + +.. _gitter: https://gitter.im/matplotlib/matplotlib From eae7135b68890b1215811fd2d7c6d63ebee30568 Mon Sep 17 00:00:00 2001 From: melissawm Date: Tue, 14 Feb 2023 13:10:58 -0300 Subject: [PATCH 2/7] Addressing reviewer comments; reorganization and rewording --- doc/devel/contributing.rst | 113 ++++++++++++++++++------------------- 1 file changed, 56 insertions(+), 57 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 52f2d349cabd..697168839682 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -19,6 +19,57 @@ is expected to abide by our Below, you can find a number of ways to contribute, and how to connect with the Matplotlib community. +.. _start-contributing: + +Is there a recommended way to get started with contributing? +------------------------------------------------------------ + +There is no pre-defined pathway for new contributors, but in practical terms - +looking at subsets of the Matplotlib source code is reasonable, as is looking at +existing issue and pull request discussions. You can learn a lot from the +observations and corrections that come up in code review, for example. + +There are a few very 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.** + + This is how a lot of people approach open-source development. 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.** + + In this case, even if you need help with programming skills or don't know + where to start, 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; you can open a (draft or not) pull request with a starting + point, and we'll be happy to discuss technical approaches. + +* **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 and + choosing something to focus on (3d, testing, documentation, animations, etc.) + and gaining context on this area by reading from issues and pull requests + touching these subjects is a reasonable approach. + Get Connected ============= @@ -36,11 +87,11 @@ Contributor incubator --------------------- The incubator is our non-public communication channel for new contributors. It -is a private gitter_ room moderated by core Matplotlib developers where you can -get guidance and support for your first few PRs. It's a place 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 +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 gitter_ community channel, and ask to be added @@ -97,58 +148,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. -.. _start-contributing: - -Is there a recommended way to get started with contributions? -------------------------------------------------------------- - -There is no pre-defined pathway for new contributors, but in practical terms - -looking at subsets of the Matplotlib source code is reasonable, as is looking at -existing issue and pull request discussions. You can learn a lot from the -observations and corrections that come up in code review, for example. - -There are a few very 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.** - - This is how a lot of people approach open-source development. 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).** - - In this case, even if you need help with programming skills or don't know - where to start, 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; you can open a (draft or not) pull request with a starting - point, and we'll be happy to discuss technical approaches. - -* **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 and - choosing something to focus on (3d, testing, documentation, animations, etc.) - and building your way up from issues and pull requests touching these subjects - is a reasonable approach. - - .. _submitting-a-bug-report: Submitting a bug report From 012e4e7b72d69b6429470a2d7d842ff08dddea67 Mon Sep 17 00:00:00 2001 From: melissawm Date: Tue, 14 Feb 2023 13:14:10 -0300 Subject: [PATCH 3/7] Added link to draft PR documentation --- doc/devel/contributing.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 697168839682..2734a1f8b500 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -49,8 +49,10 @@ There are a few very typical new contributor profiles: In this case, even if you need help with programming skills or don't know where to start, 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; you can open a (draft or not) pull request with a starting - point, and we'll be happy to discuss technical approaches. + implementation; you can open a 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. * **You are new to Matplotlib, both as a user and contributor, and want to start contributing but have yet to develop a particular interest.** From 8880d31f0636c54eb8906e06b9fa90a6ff7af4f7 Mon Sep 17 00:00:00 2001 From: melissawm Date: Tue, 14 Feb 2023 13:37:03 -0300 Subject: [PATCH 4/7] Reword intro to new contributors --- doc/devel/contributing.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 2734a1f8b500..2eaccf9e80e4 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -24,10 +24,10 @@ Matplotlib community. Is there a recommended way to get started with contributing? ------------------------------------------------------------ -There is no pre-defined pathway for new contributors, but in practical terms - -looking at subsets of the Matplotlib source code is reasonable, as is looking at -existing issue and pull request discussions. You can learn a lot from the -observations and corrections that come up in code review, for example. +There is no pre-defined pathway for new contributors, but in practical terms you +can look at existing issues and pull request discussions, as well as subsets +of the Matplotlib source code. You can learn a lot from the observations and +corrections that come up in code review, for example. There are a few very typical new contributor profiles: From ce872a4f19359ab8e281b77ccfd9dc5eeab8a198 Mon Sep 17 00:00:00 2001 From: melissawm Date: Tue, 14 Feb 2023 14:50:43 -0300 Subject: [PATCH 5/7] Fix header sequence --- doc/devel/contributing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 2eaccf9e80e4..124f42337ca1 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -22,7 +22,7 @@ Matplotlib community. .. _start-contributing: Is there a recommended way to get started with contributing? ------------------------------------------------------------- +============================================================ There is no pre-defined pathway for new contributors, but in practical terms you can look at existing issues and pull request discussions, as well as subsets @@ -97,8 +97,8 @@ 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 gitter_ community channel, and ask to be added -added to `#incubator`. One of our core developers will see your message and will -add you. +added to ``#incubator``. One of our core developers will see your message and +will add you. New Contributors meeting ------------------------ From c06752a521535c454f72f46dba248bd8141d46da Mon Sep 17 00:00:00 2001 From: melissawm Date: Tue, 14 Feb 2023 14:55:27 -0300 Subject: [PATCH 6/7] Address code review comments --- doc/devel/contributing.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 124f42337ca1..cd930731c134 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -21,15 +21,15 @@ Matplotlib community. .. _start-contributing: -Is there a recommended way to get started with contributing? -============================================================ +Getting started with contributing? +================================== -There is no pre-defined pathway for new contributors, but in practical terms you -can look at existing issues and pull request discussions, as well as subsets -of the Matplotlib source code. You can learn a lot from the observations and -corrections that come up in code review, for example. +There is no pre-defined pathway for new contributors; you can look at existing +issue and pull request discussions, and follow the discussions during code +review. Or you can deep-dive into a subset of code-base to understand what is +going on. -There are a few very typical new contributor profiles: +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.** @@ -49,8 +49,8 @@ There are a few very typical new contributor profiles: In this case, even if you need help with programming skills or don't know where to start, 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; you can open a pull request with a starting point, and we'll - be happy to discuss technical approaches. If you prefer, you can use the + implementation; you can 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. From 5560241d1335dc7dc4657a02095b8f259cded6a7 Mon Sep 17 00:00:00 2001 From: melissawm Date: Fri, 10 Mar 2023 09:46:57 -0300 Subject: [PATCH 7/7] Responding to reviewers' comments --- doc/devel/contributing.rst | 43 ++++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 20 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index cd930731c134..91f4fdfcddf0 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -24,35 +24,38 @@ Matplotlib community. Getting started with contributing? ================================== -There is no pre-defined pathway for new contributors; you can look at existing -issue and pull request discussions, and follow the discussions during code -review. Or you can deep-dive into a subset of code-base to understand what is -going on. +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. 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.** - This is how a lot of people approach open-source development. 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 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.** - In this case, even if you need help with programming skills or don't know - where to start, you have a focus on a specific application and domain and can + 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; you can 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 + 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. + 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.** @@ -67,9 +70,9 @@ There are a few typical new contributor profiles: 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 and + 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 from issues and pull requests + and gaining context on this area by reading the issues and pull requests touching these subjects is a reasonable approach. Get Connected @@ -97,7 +100,7 @@ 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 gitter_ community channel, and ask to be added -added to ``#incubator``. One of our core developers will see your message and +to ``#incubator``. One of our core developers will see your message and will add you. New Contributors meeting @@ -115,7 +118,7 @@ new_contributor_meeting>`_. 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 <3 feedback! +suggestions. We ❤ feedback! .. _new_contributors: