From b2f5cab1f86ff1d5fae2e8b07a5361e81572c664 Mon Sep 17 00:00:00 2001 From: hannah Date: Wed, 21 Jun 2023 03:47:31 -0400 Subject: [PATCH] reorganize contribute page into blocks and cards changed buttons into clickable cards + code spaces placeholder Co-authored-by: Ruth Comer <10599679+rcomer@users.noreply.github.com> --- doc/devel/contribute.rst | 7 +- doc/devel/development_setup.rst | 4 +- doc/devel/development_workflow.rst | 18 ++-- doc/devel/index.rst | 165 ++++++++++++++++++++--------- doc/devel/triage.rst | 4 + 5 files changed, 138 insertions(+), 60 deletions(-) diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst index c6e1a2199fae..cca7d09ffca2 100644 --- a/doc/devel/contribute.rst +++ b/doc/devel/contribute.rst @@ -18,6 +18,8 @@ contribute. Everyone within the community is expected to abide by our `code of conduct `_. + + Below, you can find a number of ways to contribute, and how to connect with the Matplotlib community. @@ -77,7 +79,9 @@ There are a few typical new contributor profiles: and gaining context on this area by reading the issues and pull requests touching these subjects is a reasonable approach. -Get Connected +.. _get_connected: + +Get connected ============= Do I really have something to contribute to Matplotlib? @@ -145,6 +149,7 @@ though not necessarily all at the same time: - It involves Python features such as decorators and context managers, which have subtleties due to our implementation decisions. +.. _managing_issues_prs: Work on an issue ---------------- diff --git a/doc/devel/development_setup.rst b/doc/devel/development_setup.rst index 837aa05b8b4e..336d96933301 100644 --- a/doc/devel/development_setup.rst +++ b/doc/devel/development_setup.rst @@ -148,8 +148,8 @@ The simplest way to do this is to use either Python's virtual environment Remember to activate the environment whenever you start working on Matplotlib. -Installing Matplotlib in editable mode -====================================== +Install Matplotlib in editable mode +=================================== Install Matplotlib in editable mode from the :file:`matplotlib` directory using the command :: diff --git a/doc/devel/development_workflow.rst b/doc/devel/development_workflow.rst index 85b6408a6cb7..e72bb536c43b 100644 --- a/doc/devel/development_workflow.rst +++ b/doc/devel/development_workflow.rst @@ -145,8 +145,8 @@ If you don't think your request is ready to be merged, just say so in your pull request message and use the "Draft PR" feature of GitHub. This is a good way of getting some preliminary code review. -Some other things you might want to do -====================================== +Manage commit history +===================== Explore your repository ----------------------- @@ -163,8 +163,8 @@ To see a linear list of commits for this branch:: .. _recovering-from-mess-up: -Recovering from mess-ups ------------------------- +Recover from mistakes +--------------------- Sometimes, you mess up merges or rebases. Luckily, in git it is relatively straightforward to recover from such mistakes. @@ -193,8 +193,8 @@ If you forgot to make a backup branch:: .. _rewriting-commit-history: -Rewriting commit history ------------------------- +Rewrite commit history +---------------------- .. note:: @@ -285,7 +285,7 @@ to replace your already published commits with the new ones. .. _rebase-on-main: -Rebasing on ``upstream/main`` +Rebase onto ``upstream/main`` ----------------------------- Let's say you thought of some work you'd like to do. You @@ -363,8 +363,8 @@ to replace your already published commits with the new ones. .. _force-push: -Pushing, with force -------------------- +Push with force +--------------- If you have in some way re-written already pushed history (e.g. via diff --git a/doc/devel/index.rst b/doc/devel/index.rst index 79838607f586..13a25efcedd0 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -5,72 +5,141 @@ Contribute ########## Thank you for your interest in helping to improve Matplotlib! There are various -ways to contribute to Matplotlib. All of them are super valuable! For example: +ways to contribute: optimizing and refactoring code, detailing unclear +documentation and writing new examples, reporting and fixing bugs and requesting +and implementing new features, helping the community... -- cleaning up and optimizing the code base -- creating and sharing examples of using the library -- detailing unclear and missing documentation -- reporting and fixing bugs -- requesting and implementing new features -- helping the community with all of the above +.. card:: + .. grid:: 1 1 2 2 -If you have any questions on the -process or how to fix something feel free to ask on `gitter -`_ for short questions and on -`discourse `_ for longer questions. + .. grid-item:: + :class: sd-fs-5 + :child-align: spaced -.. rst-class:: sd-d-inline-block + :octicon:`info;1em;sd-text-info` :ref:`Where should I start? ` - .. button-ref:: submitting-a-bug-report - :class: sd-fs-6 - :color: primary + :octicon:`question;1em;sd-text-info` :ref:`Where should I ask questions? ` - Report a bug + :octicon:`issue-opened;1em;sd-text-info` :ref:`What are "good-first-issues"? ` -.. rst-class:: sd-d-inline-block + :octicon:`git-pull-request;1em;sd-text-info` :ref:`How do I claim an issue? ` - .. button-ref:: request-a-new-feature - :class: sd-fs-6 - :color: primary + .. :octicon:`codespaces;1em;sd-text-info` placeholder for codespaces link - Request a feature + .. grid-item:: -.. rst-class:: sd-d-inline-block + .. grid:: 1 + :gutter: 1 + :class-row: sd-fs-5 - .. button-ref:: contributing-code - :class: sd-fs-6 - :color: primary + .. grid-item-card:: + :link: request-a-new-feature + :link-type: ref - Contribute code + :octicon:`light-bulb;1em;sd-text-info` Request new feature -.. rst-class:: sd-d-inline-block + .. grid-item-card:: + :link: submitting-a-bug-report + :link-type: ref - .. button-ref:: documenting-matplotlib - :class: sd-fs-6 - :color: primary + :octicon:`bug;1em;sd-text-info` Submit bug report - Write documentation + .. grid-item-card:: + :link: contributing-code + :link-type: ref -.. toctree:: - :maxdepth: 2 - - contribute.rst - triage.rst - development_setup.rst - development_workflow.rst - testing.rst - document.rst - style_guide.rst - coding_guide.rst - release_guide.rst - dependencies.rst - min_dep_policy.rst - maintainer_workflow.rst - MEP/index + :octicon:`code;1em;sd-text-info` Contribute code + + .. grid-item-card:: + :link: documenting-matplotlib + :link-type: ref + + :octicon:`note;1em;sd-text-info` Write documentation + +If you are new to contributing, we recommend that you first read our +:ref:`contributing guide`. If you are contributing code or +documentation, please follow our guides for setting up and managing a +:ref:`development environment and workflow`. +For code, documentation, or triage, please follow the corresponding +:ref:`contribution guidelines `. + + +.. _development_environment: + +Development workflow +==================== + +.. grid:: 1 1 2 2 + + .. grid-item-card:: Install + + .. toctree:: + :maxdepth: 2 + + development_setup + + .. toctree:: + :maxdepth: 1 + + dependencies + Minimum versions + + + .. grid-item-card:: Workflow + + .. toctree:: + :maxdepth: 2 + + development_workflow + + + +.. _contribution_guideline: + +Contribution guides +=================== + +.. grid:: 1 1 2 2 + :class-row: sf-fs-1 + + .. grid-item-card:: Code + + | :ref:`coding_guidelines` + + .. toctree:: + :maxdepth: 1 + + coding_guide + testing + + .. grid-item-card:: Documentation + + .. toctree:: + :maxdepth: 1 + + document + style_guide + + .. grid-item-card:: Triage + + | :ref:`bug_triaging` + | :ref:`triage_team` + | :ref:`triage_workflow` + + .. grid-item-card:: Maintenance + + .. toctree:: + :maxdepth: 1 + + maintainer_workflow + release_guide + MEP/index .. toctree:: :hidden: - license.rst + contribute + triage + license color_changes diff --git a/doc/devel/triage.rst b/doc/devel/triage.rst index c650a6f6150b..58574159af5c 100755 --- a/doc/devel/triage.rst +++ b/doc/devel/triage.rst @@ -62,6 +62,8 @@ The following actions are typically useful: explores how to lead online discussions in the context of open source. +.. _triage_team: + Triage team ----------- @@ -121,6 +123,8 @@ can do the following important tasks: should be closed. +.. _triage_workflow: + A typical workflow for triaging issues --------------------------------------