From 7941c368cd01040c96d8e0f667555c02f28582a2 Mon Sep 17 00:00:00 2001 From: Ian Hunt-Isaak Date: Sat, 23 Jan 2021 00:40:49 -0500 Subject: [PATCH 1/6] add a header paragraph to the top level contributing tab + Reword contributing opening paragraph Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> --- doc/devel/index.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/doc/devel/index.rst b/doc/devel/index.rst index 0c94454e6285..85d111b9bb43 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -4,6 +4,21 @@ The Matplotlib Developers' Guide ################################ +Thank you for your interest in helping to improve Matplotlib! There are various +ways to contribute to Matplotlib. All of them are super valuable but don't necessarily +require writing code at all. For example: + +- contributing to the documentation +- opening new issues for bugs +- requesting new features +- asking for clarification on things you find unclear +- fixing bugs + +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. + .. raw:: html
From 297070ad6da3c565abca2b1a80f128d0d87757c2 Mon Sep 17 00:00:00 2001 From: Ian Hunt-Isaak Date: Sat, 23 Jan 2021 00:42:59 -0500 Subject: [PATCH 2/6] add install step to the Contributing code also remove the $ as they make it more difficult for readers to copy paste link to more detailed dev install instructions only link to install page in brief set up docs. --- doc/devel/contributing.rst | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 850be2ac6138..ea7a2cc120c1 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -102,27 +102,29 @@ A brief overview is: 3. Clone this copy to your local disk:: - $ git clone https://github.com/YourLogin/matplotlib.git + git clone https://github.com//matplotlib.git -4. Create a branch to hold your changes:: +4. Enter the directory and install the local version of Matplotlib. + See ref`` for instructions - $ git checkout -b my-feature origin/master +5. Create a branch to hold your changes:: + + git checkout -b my-feature origin/master and start making changes. Never work in the ``master`` branch! -5. Work on this copy, on your computer, using Git to do the version control. +6. Work on this copy, on your computer, using Git to do the version control. When you're done editing e.g., ``lib/matplotlib/collections.py``, do:: - $ git add lib/matplotlib/collections.py - $ git commit + git add lib/matplotlib/collections.py + git commit to record your changes in Git, then push them to GitHub with:: - $ git push -u origin my-feature + git push -u origin my-feature Finally, go to the web page of your fork of the Matplotlib repo, and click -'Pull request' to send your changes to the maintainers for review. You may -want to consider sending an email to the mailing list for more visibility. +'Pull request' to send your changes to the maintainers for review. .. seealso:: From bae3bade7c95c8b8bc02561bbeee9fa34d77171d Mon Sep 17 00:00:00 2001 From: Ian Hunt-Isaak Date: Sat, 23 Jan 2021 00:46:00 -0500 Subject: [PATCH 3/6] move issues for new contributors higher up on the page it seems to pair well with the contributor incubator part, and it was somewhat hard to notice where it used to be. --- doc/devel/contributing.rst | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index ea7a2cc120c1..8d36fdb6ccc3 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -25,6 +25,19 @@ about the code, what makes for good documentation or a blog post, how to get inv in community work, or get "pre-review" on your PR. +.. _new_contributors: + +Issues for New Contributors +--------------------------- + +New contributors should look for the following tags when looking for issues. +We strongly recommend that new contributors tackle issues labeled +`good first issue `_ +as they are easy, well documented issues, that do not require an understanding of +the different submodules of Matplotlib. +This helps the contributor become familiar with the contribution +workflow, and for the core devs to become acquainted with the contributor. + .. _submitting-a-bug-report: Submitting a bug report @@ -218,20 +231,6 @@ tools: -.. _new_contributors: - -Issues for New Contributors ---------------------------- - -New contributors should look for the following tags when looking for issues. -We strongly recommend that new contributors tackle issues labeled -`good first issue `_ -as they are easy, well documented issues, that do not require an understanding of -the different submodules of Matplotlib. -This helps the contributor become familiar with the contribution -workflow, and for the core devs to become acquainted with the contributor; -besides which, we frequently underestimate how easy an issue is to solve! - .. _contributing_documentation: From 98971ac23d11cd7c47e4808aa4f58fd16c4ff8de Mon Sep 17 00:00:00 2001 From: Ian Hunt-Isaak Date: Sat, 23 Jan 2021 00:47:15 -0500 Subject: [PATCH 4/6] update the versions to modern versions Less mental effort to read this, as no time spent thinking about how different your versions are. --- doc/devel/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 8d36fdb6ccc3..a9c50e4bad21 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -66,10 +66,10 @@ If you are reporting a bug, please do your best to include the following: >>> import matplotlib >>> matplotlib.__version__ - '1.5.3' + '3.4.1' >>> import platform >>> platform.python_version() - '2.7.12' + '3.9.2' We have preloaded the issue creation page with a Markdown template that you can use to organize this information. From ea230e323ab634ad15bd0f4d8b45dd71ecda0c66 Mon Sep 17 00:00:00 2001 From: Ian Hunt-Isaak Date: Sat, 23 Jan 2021 00:57:15 -0500 Subject: [PATCH 5/6] Remove early link to gitwash and place description in the see also It's super easy to click on that link and then get bogged down in details rather than read the short guide that follows that paragraph. --- doc/devel/contributing.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index a9c50e4bad21..92dea3638614 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -101,9 +101,6 @@ The preferred way to contribute to Matplotlib is to fork the `main repository `__ on GitHub, then submit a "pull request" (PR). -The best practices for using GitHub to make PRs to Matplotlib are -documented in the :ref:`development-workflow` section. - A brief overview is: 1. `Create an account `_ on GitHub if you do not @@ -144,7 +141,7 @@ Finally, go to the web page of your fork of the Matplotlib repo, and click * `Git documentation `_ * `Git-Contributing to a Project `_ * `Introduction to GitHub `_ - * :ref:`development-workflow` + * :ref:`development-workflow` for best practices for Matplotlib * :ref:`using-git` Contributing pull requests From 7965576a8a176080a21689532b48130a794ba5e8 Mon Sep 17 00:00:00 2001 From: Ian Hunt-Isaak Date: Wed, 3 Feb 2021 22:02:59 -0500 Subject: [PATCH 6/6] Clarify description of good first issues Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> --- doc/devel/contributing.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 92dea3638614..aaaec72c00ca 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -30,13 +30,14 @@ in community work, or get "pre-review" on your PR. Issues for New Contributors --------------------------- -New contributors should look for the following tags when looking for issues. -We strongly recommend that new contributors tackle issues labeled +While any contributions are welcome, we have marked some issues as +particularly suited for new contributors by the label `good first issue `_ -as they are easy, well documented issues, that do not require an understanding of -the different submodules of Matplotlib. -This helps the contributor become familiar with the contribution -workflow, and for the core devs to become acquainted with the contributor. +These are well documented issues, that do not require a deep understanding of +the internals of Matplotlib. The issues may additionally be tagged with a +difficulty. ``Difficulty: Easy`` is suited for people with little Python experience. +``Difficulty: Medium`` and ``Difficulty: Hard`` are not trivial to solve and +require more thought and programming experience. .. _submitting-a-bug-report: