updated contribution doc #28476 #28871
Conversation
There was a problem hiding this comment.
Thank you for opening your first PR into Matplotlib!
If you have not heard from us in a week or so, please leave a new comment below and that should bring it to our attention. Most of our reviewers are volunteers and sometimes things fall through the cracks.
You can also join us on gitter for real-time discussion.
For details on testing, writing docs, and our review process, please see the developer guide
We strive to be a welcoming and open project. Please follow our Code of Conduct.
|
Will take a look soon, thanks for getting this in! Did you install the pre-commit hooks? The error is complaining about extra lines, which should be fixed by the hooks |
Just installed pre-commit and pushed changes up to the PR, thank you! |
There was a problem hiding this comment.
I'm beyond psyched that a new contributor is writing guidance for new contributors and I like the straightforwardness. The important requested changes are to pull the guidance in line with how the project currently operates so everyone is working with the same expectations. Everything else is more suggestions and you may know better as the new contributor.
doc/devel/contribute.rst
Outdated
| .. _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 <https://github.com/matplotlib/matplotlib/issues/>`_. | ||
| 2. Filter labels with `"Difficulty: Easy" <https://github.com/matplotlib/matplotlib/labels/Difficulty%3A%20Easy>`_ & `"Good first Issue" <https://github.com/matplotlib/matplotlib/labels/good%20first%20issue>`_ (optional). | ||
| 3. Click on an issue you would like to work on, and check to see if the issue 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) <https://github.com/matplotlib/matplotlib/pulls?q=is%3Apr+is%3Aopen+%2328476>`_ 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. |
There was a problem hiding this comment.
How do you feel about making this a subsection of choosing an issue, possibly as it's own call out/open drop down?
There was a problem hiding this comment.
I think dedicating own call out/drop down is a good move. I would keep 'choose an issue' in the same place and move 'Good first issues' & 'First Contributions & New Contributions in a "New Contributors" callout/dropdown
There is going to slight information redundancy, between what is in "Choose an Issue" and the "New Contributors" section, but I think that is ok. Idea here is new folks can just stay in that 1 section and have it walk through each step (reduce friction).
There was a problem hiding this comment.
Agree, keep choosing an issue where it is and move the new contributor guidance into an open by default drop down in choosing an issue
doc/devel/contribute.rst
Outdated
| 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) <https://github.com/matplotlib/matplotlib/pulls?q=is%3Apr+is%3Aopen+%2328476>`_ 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. |
There was a problem hiding this comment.
| 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. | |
| 6. After steps 3 & 4 are done, if no one is working on the issue then comment on the issue to state you are working on it. |
Honestly, we prefer that folks don't do this b/c we have a lot of folks who say they're going to and then don't follow up and it's left for us to moderate (somewhat inconsistently). We'd much prefer that folks just open a draft (incomplete) PR if they're seriously working on something.
There was a problem hiding this comment.
This would be an organizational decision, but maybe set max time of no activity: no active comments/discussions within issue or idle/open PR, people can just work on the issue. This way you dont need to moderate, simple yes/no check. If inactive >1 month, free to take, else, try to contact the original contributor.
Let me know what you think, because I think you're suggesting we just drop that entire line and rewrite it to include drafts?
There was a problem hiding this comment.
Yeah that's what I'm suggesting b/c we have discussed it and at the time the consensus was claiming via draft.
There was a problem hiding this comment.
Granted I like your idea, so you can bring this discussion back up at next week's developer call (which I won't be at, otherwise I'd do it) https://scientific-python.org/calendars/
There was a problem hiding this comment.
Thank you for sharing the link, unfortunately I am working during the meeting and cannot attend. I also created a new PR based on your recommendations and suggestions, thank you for the guidance!
doc/devel/contribute.rst
Outdated
|
|
||
| 1. Navigate to the `issues page <https://github.com/matplotlib/matplotlib/issues/>`_. | ||
| 2. Filter labels with `"Difficulty: Easy" <https://github.com/matplotlib/matplotlib/labels/Difficulty%3A%20Easy>`_ & `"Good first Issue" <https://github.com/matplotlib/matplotlib/labels/good%20first%20issue>`_ (optional). | ||
| 3. Click on an issue you would like to work on, and check to see if the issue is already claimed. |
There was a problem hiding this comment.
| 3. Click on an issue you would like to work on, and check to see if the issue is already claimed. | |
| 3. Click on an issue you would like to work on, and check to see if a PR has been opened to resolve this issue. |
As written at the start of the issues section, we don't officially acknowledge claiming an issue except by opening a PR intending to resolve it.
doc/devel/contribute.rst
Outdated
| 2. Filter labels with `"Difficulty: Easy" <https://github.com/matplotlib/matplotlib/labels/Difficulty%3A%20Easy>`_ & `"Good first Issue" <https://github.com/matplotlib/matplotlib/labels/good%20first%20issue>`_ (optional). | ||
| 3. Click on an issue you would like to work on, and check to see if the issue 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) <https://github.com/matplotlib/matplotlib/pulls?q=is%3Apr+is%3Aopen+%2328476>`_ and filter by the issue number to make sure the issue is not in progress. |
There was a problem hiding this comment.
| 5. Check the `pull requests (i.e. #28476) <https://github.com/matplotlib/matplotlib/pulls?q=is%3Apr+is%3Aopen+%2328476>`_ and filter by the issue number to make sure the issue is not in progress. | |
| 5. Check the pull requests (i.e. :ghpull:`28476`) and filter by the issue number to make sure the issue is not in progress. |
doc/devel/contribute.rst
Outdated
| 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 <https://matplotlib.org/devdocs/devel/pr_guide.html>'_. |
There was a problem hiding this comment.
| 6. After steps 3 & 5 are done, and a PR does not exist, open a 'draft (incomeplete) PR <https://matplotlib.org/devdocs/devel/pr_guide.html>'_. | |
| 6. After steps 3 & 5 are done, and a PR does not exist, open a `draft (incomeplete) PR <https://matplotlib.org/devdocs/devel/pr_guide.html>`_. |
There was a problem hiding this comment.
Also I don't think you need the (incomplete) - draft can be complete for now
There was a problem hiding this comment.
Thank you for the recommendations, all changes have been made and pushed up
|
I think some wires got crossed on the last round of feedback b.c now if you look at the new rendered page/structure, it doesn't at all line up w/ the landing page and also casts everything as being for new contributors when there's a mix of things there.
My guess is that some of this is a heading issue, see https://matplotlib.org/devdocs/devel/document.html#section-formatting for the correct levels. What I'd intended to suggest was the following structure:
If you think grouping all the new contributor stuff together makes more sense, that's fine, but the overall structure on the landing page and contributing guide should match and we really want the guide to not just be geared to first time open source contributors because we also want to communicate process (like don't snipe PRs) to folks who aren't new contributors. |
I think I am following: youre saying the contributing guide section at the index should match the structure of the contribution guide page. If my understanding of your comments is right, I dont think its necessary to have the sections of "Contribution guide" in index match the structure of the actual contribution guide. At the index level, I like the current content because it captures what likely are FAQs, and I can add a section for first time contributors at the index level. I was following your initial suggestion , and "Get Started" and "First Open Source Contribution & New Contributors" became their own sections based on the conversations here. Personally, I dont think the current contribution guide "casts everything as being for new contributors," outside the last section. The only change needed in my opinion is to add a "First Contributor" section in the Contribution Guide on the index page. Let me know what you think and I can make the changes! |
So I think is is where wires got crossed b/c that hollow circles were supposed to be subheadings. What I had intended with that structure was:
So that basically the content breaks out this way What is implemented in this PR moves a lot of the get started content under get connected: If this was intentional, please explain to my why that move is an improvement. The reason I think it could have been unintentional is that I may have been sloppy in an earlier review and suggested the wrong section level for a heading. Just to make sure we're talking about the same thing and just in case you missed it, you can see how the page renders by clicking the following in the checks pane:
I think maybe the "where should I start" link could get repurposed for that. The reason I am suggesting that the new "first contributor" section go in as a subsection of issues is b/c all the guidance you've given is specific to choosing an issue and does not discuss any other type of new contribution, but I also understand if you feel that would bury it too much. |
Alright I see the issue, the restructuring was from a combination of the feedback and improper execution on my part. I do see your point for the current structure: not very logical. As for the "first contributor section," I understood it is somewhat redundant and mentioned that. I think for the target audience, having it as a main section (to always show in the right hand side menu) is better to minimize the friction for first timers, otherwise the "first contributors" may get lost while looking for guidance.documentation. What do you think about this structure:
There is likely more content we can add to the "First Contributors" section, and could be a separate issue. Preface, the additional content that would be added to the "First Contributors" section will likely be redundant, and I think that is ok, since were trying to reduce friction for first contributors. This should translate to reduced time for matplotlib's admins answering similar questions from first contributors: I am also assuming you receive similar questions/issues across first contributors. Though all the information first contributors are seeking exists either in matplotlib's documentation, or on the web, there is value in aggregating and explicitly laying out what first contributors should do/read. Let me know if there is anything I can expand on/further explain about the new proposed structure. We can also chat about what additional content could be added 'first contributors' section to have the new/current structure reflect the future state. |
|
Broadly I like your suggestion, but with the following tweak b/c in a follow up PR I plan to integrate the PR workflow/open a pull request section into the development workflow documentation because some of the feedback from sprints is that it's confusing to have to leave the contributing guide to do all the install steps and then come back for the workflow that's also in the other workflow section.
Also following this structure, maybe swap the index cards:
My concern is more that breaking up the related information may cause new contributors to think it doesn't apply to them -> like thinking about how to restructure the index link when both incubator and new contributor meetings are ways of getting connected or how the issue policies work. Which I guess here I'm flipping the structure so that new contributors won't just jump to the end. |
I like your changes, and do not think contributors will think sections do not apply to them: because if they stop reading after the new contributor section, they should realize there are additional steps needed. Moving the 'Get Started' section is a good call, it helps the page flow better and keep the content focused around contributing. |
|
Ack just realized I forgot to delete the get connected paragraph, so just so we're on the same page, this is what I'm suggesting: Ways to contribute New contributors (mostly cause short titles are preferable) Get Started |
|
Also cause this is sorta pulling back to how this was originally structured, going back to that (https://matplotlib.org/3.6.3/devel/contributing.html#get-connected, https://matplotlib.org/3.7.5/devel/contributing.html) has me thinking that maybe the "what do I have to contribute?" drop down should go under the new contributors section (eta) or maybe leave it as a pep talk before ways to contribute - clearly I'm feeling indecisive about this. |
Your most recent structure is a good layout for the current content and future additions (if need be). The headers are concise, and captures the main topics of the page. The "what do I have to contribute?" section's location is good where it is, because it is applicable to all contributors, and sets the stage for the rest of the page: pep talk it is :). I think we roll out the changes I will make, based on the new proposed structure, see how it reads, and iterate if need be. If you want to this PR to pivot to redoing and refining the entire contribution page, let's chat a bit more about what the team wants the page to accomplish. To me, the page should be a high level breakdown on contributing, and include many links to other pages: from what I can tell, the content in the 3.6.3 and 3.7.5 may have been too detailed on the contribution page, which is why they live in other parts of the dev docs. |
Sorry if that's how it came across but no I think that's out of scope here. I think if you're interested in doing a full rework then that should be a new issue/proposal. I agree that this PR should stay focused on what we've already discussed:
I don't know which sections 3.6.3 and 3.7.5 are referring. |
Alright cool, we are on the same page and should limit this PR to the original issue (your two bullets). I'll start the edits now. Not relevant anymore, but I was referring to the versions in these links "Also cause this is sorta pulling back to how this was originally structured, going back to that (https://matplotlib.org/**3.6.3**/devel/contributing.html#get-connected, https://matplotlib.org/**3.7.5**/devel/contributing.html)" |
You are right. Not sure how that happened and I have sorted it out, thank you! |
doc/devel/index.rst
Outdated
| @@ -71,7 +71,7 @@ Since Matplotlib is an open source project with limited resources, we encourage | ||
| to also :ref:`participate <contribute_code>` in fixing bugs and implementing new | ||
| features. | ||
|
|
||
| Contributing guide | ||
| Contribution guide |
No worries at all, thank you for all the help and guidance! |
No problem, thank you for your help as well! I am thinking squash merge to keep things clean if that works for you. |
|
Congrats on your first contribution, hope to hear from you again! 🥳 |
Cheers, thank you for the help! |
PR summary
Issue #28476
PR checklist