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
https://matplotlib.org/devdocs/devel/development_setup.html#install-pre-commit-hooks

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 hookshttps://matplotlib.org/devdocs/devel/development_setup.html#install-pre-commit-hooks

Just installed pre-commit and pushed changes up to the PR, thank you!

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.
https://output.circle-artifacts.com/output/job/2c79daaf-7fff-40ee-a4c7-c5e1290199f4/artifacts/0/doc/build/html/devel/contribute.html#contributing

My guess is that some of this is a heading issue, seehttps://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 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.https://output.circle-artifacts.com/output/job/2c79daaf-7fff-40ee-a4c7-c5e1290199f4/artifacts/0/doc/build/html/devel/contribute.html#contributing

My guess is that some of this is a heading issue, seehttps://matplotlib.org/devdocs/devel/document.html#section-formatting for the correct levels.

What I'd intended to suggest was the following structure:

landing page linkcorresponding section in contribute guide link
where should I start1. get started
  a. "do I really have something to contribute" dropdown here
where should I ask questions2. get connected
  a. incubator
  b. new contributor meeting
how do I choose an issue3. choose an issue
  a. good first issues
  b. first contributions
how do I start a pull request4. start a pull request
  a. workflow overview
  b. open a pull request on matplotlib
contribute code5. ways to contribute
  a. code
write documentation5. ways to contribute
  b. documentation
triage issues5. ways to contribute
  c. triage
build community5. ways to contribute
  d. community
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 contributingguide section at the index should match the structure of thecontribution 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 actualcontribution 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 initialsuggestion, 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!

I was following your initial#28476 (comment), and "Get Started" and "First Open Source Contribution & New Contributors" became their own sections based on the conversations here.

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:

• get started
  • get connected
  • choose an issue
  • start a pull request

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:

The only change needed in my opinion is to add a "First Contributor" section in the Contribution Guide on the index page.

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.

I was following your initial#28476 (comment), and "Get Started" and "First Open Source Contribution & New Contributors" became their own sections based on the conversations here.

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:

• get started

  • get connected
  • choose an issue
  • start a pull request

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:

The only change needed in my opinion is to add a "First Contributor" section in the Contribution Guide on the index page.

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:

• Ways to contribute
  -- Code
  -- Documentation
  -- Triage
  -- Community
• Get Started
  -- Choose an issue
  -- Start a pull request
  -- Workflow overview
  -- Open a pull request on Matplotlib
• First Open Source Contribution & New Contributors
  -- New Contributors Meeting
  -- Good First Issues
  -- First Contributions
• Get connected: Contributor incubator (I would just merge both of these sections into 1. Only time these should be separated is if there is more content to add relating to "Get Connected.")

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 thedevelopment 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.

• Ways to contribute
  -- Code
  -- Documentation
  -- Triage
  -- Community

• New contributors (mostly cause short titles are preferable)
  -- New Contributors Meeting
  -- Good First Issues
  -- First Contributions

• Get Started
  -- Get connected: Contributor incubator
  -- Choose an issue
  -- Start a pull request
  ---- Workflow overview
  ---- Open a pull request on Matplotlib
  (b/c I plan to move most of this)

  Get connected: Contributor incubator (I would just merge both of these sections into 1. Only time these should be separated is if there is more content to add relating to "Get Connected.")

Also following this structure, maybe swap the index cards:

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.

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.

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 thedevelopment 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.

• Ways to contribute
  -- Code
  -- Documentation
  -- Triage
  -- Community
• New contributors (mostly cause short titles are preferable)
  -- New Contributors Meeting
  -- Good First Issues
  -- First Contributions
• Get Started
  -- Get connected: Contributor incubator
  -- Choose an issue
  -- Start a pull request
  ---- Workflow overview
  ---- Open a pull request on Matplotlib
  (b/c I plan to move most of this)
  Get connected: Contributor incubator (I would just merge both of these sections into 1. Only time these should be separated is if there is more content to add relating to "Get Connected.")

Also following this structure, maybe swap the index cards:

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.

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
-- Code
-- Documentation
-- Triage
-- Community

New contributors (mostly cause short titles are preferable)
-- New Contributors Meeting
-- Good First Issues
-- First Contributions

Get Started
-- Get connected: Contributor incubator
-- Choose an issue
-- Start a pull request
---- Workflow overview
---- Open a pull request on Matplotlib
(b/c I plan to move most of this)

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.

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.

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:

• matching index page to structure
• adding first time contributor specific content and (with the discussed moves to clean up structure)

I don't know which sections 3.6.3 and 3.7.5 are referring.

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:

• matching index page to structure
• adding first time contributor specific content and (with the discussed moves to clean up structure)

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)"

I think you may have accidentally committed all the files in a rebase or your local environment? Can you fix the rebase or would you like help to do so?

You are right. Not sure how that happened and I have sorted it out, thank you!

Thank you so much for your patience - just a few minor things and then it should be good to go provided nobody else objects.

No worries at all, thank you for all the help and guidance!

Looks great! Thank you for all the work you've done on this and I'm very excited for it to get into the docs right in time for sprints and a new release.

I'm just waiting on doc build for merging, let me know if you want to rebase or for me to squash merge.

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! 🥳

Congrats on your first contribution, hope to hear from you again! 🥳

Cheers, thank you for the help!