8000 DOC: Add section on how to start contributing by melissawm · Pull Request #25214 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

DOC: Add section on how to start contributing #25214

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
May 2, 2023
Merged

DOC: Add section on how to start contributing #25214

Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
bd3c10f
DOC: Add section on how to start contributing
melissawm Feb 14, 2023
eae7135
Addressing reviewer comments; reorganization and rewording
melissawm Feb 14, 2023
012e4e7
Added link to draft PR documentation
melissawm Feb 14, 2023
8880d31
Reword intro to new contributors
melissawm Feb 14, 2023
ce872a4
Fix header sequence
melissawm Feb 14, 2023
c06752a
Address code review comments
melissawm Feb 14, 2023
5560241
Responding to reviewers' comments
melissawm Mar 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 64 additions & 11 deletions doc/devel/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,59 @@ 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:

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
Copy link
Member
@story645 story645 Feb 14, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So I think this is slightly abrupt w/o a modfier/softner like "here is no pre-defined pathway for new contributors; we recommend, we suggest, etc" or a context setter like "to learn about some off the shelf tasks/find something that needs to get done/etc"

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good call. I rephrased

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This is how a lot of people approach open-source development. You can search
You can search

I don't think we need the first sentence? Or maybe something like "Great, to contribute a fix search..." so it feels like how the second persona is structured and is more in conversation w/ the heading"

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 <https://discourse.matplotlib.org/>`__ or attend any
of our `community meetings <https://scientific-python.org/calendars>`__.

* **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.**
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
other field where Matplotlib could be improved.**
other field where Matplotlib can be improved.**

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find the existing text to read better.


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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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
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

I think the side bit about programming skills is kinda irrelevant since we don't really mention it in the first paragraph either, and if we want to explicitly expectation set on programming skills it should be as part of the fixer persona.

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 <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#converting-a-pull-request-to-a-draft>`__
and request early feedback on whatever you are working on.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My impression is that it is much easier to get feedback if it is not in draft mode... But I agree that it would be nice if it worked as above.

Copy link
Member 8000 Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I think that is fair. How about this version?


* **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
=============

Expand All @@ -36,17 +89,16 @@ 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

blog post?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes there is a blog 😄 https://blog.scientific-python.org/tags/matplotlib/

"pre-review" on your PR.

To join, please go to our public `gitter
<https://gitter.im/matplotlib/matplotlib>`_ community channel, and ask to be
added to '#incubator'. One of our core developers will see your message and will
add you.
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
------------------------
Expand All @@ -62,8 +114,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
<https://gitter.im/matplotlib/matplotlib>`_ for any clarifications or
GitHub handles 😉. You can reach out to us on gitter_ for any clarifications or
suggestions. We <3 feedback!

.. _new_contributors:
Expand Down Expand Up @@ -543,3 +594,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
0