Skip to content

DOC: reorganizing contributing docs to clean up toc, better separate topics #27265

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

Jump to bottom
Merged
merged 3 commits into from
Dec 20, 2023
Merged

DOC: reorganizing contributing docs to clean up toc, better separate topics #27265

merged 3 commits into from
Dec 20, 2023
+1,000 −932

Conversation

story645
Copy link
Member

@story645 story645 commented Nov 3, 2023 •
edited
Loading

This is in the vein of #26196 and the high level improvement is that via reorganizing:

  • top card of the contribute landing page == roadmapped index into contribute.rst

  • each card in the policies and guidelines page is now a toctree:

image

Also much better left hand side since I understand how to make those now thanks to @jklymak (yes it took me this long to sort out that LHS goes by toctrees, like RHS goes by headers):

image

The other changes are:

PR summary

PR checklist

@story645 story645 added the Documentation: devdocs files in doc/devel label Nov 3, 2023
@story645 story645 added this to the v3.8-doc milestone Nov 5, 2023
@story645 story645 force-pushed the dev_shuffle branch 2 times, most recently from c283644 to 9053d14 Compare November 5, 2023 19:27
@story645 story645 mentioned this pull request Nov 5, 2023
Open
11 tasks
@story645 story645 force-pushed the dev_shuffle branch 3 times, most recently from 3c30056 to 3be520a Compare November 6, 2023 20:10
@story645 story645 mentioned this pull request Nov 6, 2023
Closed
@story645 story645 force-pushed the dev_shuffle branch 3 times, most recently from dc5d794 to 6522557 Compare November 6, 2023 22:30
This was referenced Nov 28, 2023
Open
Merged
@story645
Copy link
Member Author

story645 commented Dec 10, 2023 •
edited
Loading

Just want to mention that the only new content here is the documentation and coding section of the contribute guide & I'm not super attached to the language, I just wanted some content there to establish that the scope of that page is supposed to be introductory background/context setting/roadmapping for contributing and that other pages are where they can find the coding/doc/etc guides.
Also addresses part of this discussion #22866 (comment)

@story645
Copy link
Member Author

@timhoffm you might want to skim this since I move around the API guidelines a bit, but I don't change any guidelines. The changes I made specifically are:

  • moved coding guidelines out of contribute.rst and into coding_guidelines so that the page can be scoped to just coding guidelines.
  • moved API changes guidelines into its own page b/c it is as long as every other section of the coding guide->my goal here is that it is a sort of standalone/self contained part of the guide, so making it its own page keeps it from overwhelming the rest of the coding guide.
  • moved PR guidelines into it's own page b/c those guidelines apply to code and docs. My aim is also to reduce duplication between PR guidelines and coding guidelines by aggressively linking to coding guidelines and documentation guidelines and scoping PR guidelines to the PR process.

@story645 story645 force-pushed the dev_shuffle branch 7 times, most recently from 0723cb5 to 81fdb40 Compare December 19, 2023 16:25
@story645 story645 force-pushed the dev_shuffle branch 3 times, most recently from f006688 to 283e299 Compare December 19, 2023 19:29
timhoffm
timhoffm reviewed Dec 19, 2023
View reviewed changes
doc/devel/triage.rst Outdated
@@ -11,24 +12,28 @@ identifying major projects to work on, and discussing priorities. For
this reason, it is important to curate the issue list, adding labels
to issues and closing issues that are resolved or unresolvable.

Improving issues increases their chances of being successfully resolved.
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 "Improving issues" somewhat confusing, because it can have one of the two meanings:

  • work towards solving the issue (= improving an issue of the library)
  • work towards improving the issue description.

Would "Improving issue reports" be ok?

Take or leave as this has been there before. We want to take quick improvements along the way, but don't want to get lost in details.

Copy link
Member Author

Choose a reason for hiding this comment

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

reworking this language to try and make it clearer its about writing the issue.

@story645 @melissawm
reorganizing contributing docs to clean up toc
3289773 
create seperation between guidelines
make contributing guide more newbie oriented
streamline triage guide
moved api guide out of coding guidelines

Co-authored-by: Melissa Weber Mendonça <melissawm@gmail.com>
timhoffm
timhoffm approved these changes Dec 20, 2023
View reviewed changes
Copy link
Member

@timhoffm timhoffm left a comment

Choose a reason for hiding this comment

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

LGTM.

@timhoffm timhoffm merged commit 091e2ca into matplotlib:main Dec 20, 2023
@lumberbot-app Lumberbot (App)
Copy link

lumberbot-app bot commented Dec 20, 2023

Owee, I'm MrMeeseeks, Look at me.

There seem to be a conflict, please backport manually. Here are approximate instructions:

  1. Checkout backport branch and update it.
git checkout v3.8.x
git pull
  1. Cherry pick the first parent branch of the this PR on top of the older branch:
git cherry-pick -x -m1 091e2ca2e7ab0f48b826c2b8c7fbdc920803ad9c
  1. You will likely have some merge/cherry-pick conflict here, fix them and commit:
git commit -am 'Backport PR #27265: DOC: reorganizing contributing docs to clean up toc, better seperate topics'
  1. Push to a named branch:
git push YOURFORK v3.8.x:auto-backport-of-pr-27265-on-v3.8.x
  1. Create a PR against branch v3.8.x, I would have named this PR:

"Backport PR #27265 on branch v3.8.x (DOC: reorganizing contributing docs to clean up toc, better seperate topics)"

And apply the correct labels and milestones.

Congratulations — you did some good work! Hopefully your backport PR will be tested by the continuous integration and merged soon!

Remember to remove the Still Needs Manual Backport label once the PR gets merged.

If these instructions are inaccurate, feel free to suggest an improvement.

@lumberbot-app Lumberbot (App)
Copy link

lumberbot-app bot commented Dec 20, 2023

Owee, I'm MrMeeseeks, Look at me.

There seem to be a conflict, please backport manually. Here are approximate instructions:

  1. Checkout backport branch and update it.
git checkout v3.8.2-doc
git pull
  1. Cherry pick the first parent branch of the this PR on top of the older branch:
git cherry-pick -x -m1 091e2ca2e7ab0f48b826c2b8c7fbdc920803ad9c
  1. You will likely have some merge/cherry-pick conflict here, fix them and commit:
git commit -am 'Backport PR #27265: DOC: reorganizing contributing docs to clean up toc, better seperate topics'
  1. Push to a named branch:
git push YOURFORK v3.8.2-doc:auto-backport-of-pr-27265-on-v3.8.2-doc
  1. Create a PR against branch v3.8.2-doc, I would have named this PR:

"Backport PR #27265 on branch v3.8.2-doc (DOC: reorganizing contributing docs to clean up toc, better seperate topics)"

And apply the correct labels and milestones.

Congratulations — you did some good work! Hopefully your backport PR will be tested by the continuous integration and merged soon!

Remember to remove the Still Needs Manual Backport label once the PR gets merged.

If these instructions are inaccurate, feel free to suggest an improvement.

@timhoffm timhoffm modified the milestones: v3.8-doc, v3.9.0 Dec 20, 2023
@timhoffm
Copy link
Member

Removed the backport as doing this manually is not worth is IMHO.

@story645 story645 deleted the dev_shuffle branch December 20, 2023 14:38
@story645
Copy link
Member Author

Bonus of matplotlib/matplotlib.org#36 is that there's often no need to backport dev docs anymore 😁

@QuLogic QuLogic changed the title DOC: reorganizing contributing docs to clean up toc, better seperate topics DOC: reorganizing contributing docs to clean up toc, better separate topics Apr 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@melissawm melissawm melissawm left review comments

@timhoffm timhoffm timhoffm approved these changes

Assignees
No one assigned
Labels
Documentation: devdocs files in doc/devel
Projects
None yet
Milestone
v3.9.0
Development

Successfully merging this pull request may close these issues.
3 participants
@story645 @timhoffm @melissawm