ENH Improving the contribution guidelines by NelleV · Pull Request #7236 · matplotlib/matplotlib

NelleV · 2016-10-08T03:45:04Z

Here is a first attempt at improving our documentation on how to contribute. It is greatly inspired from the scikit-learn. I tried to merge all documents into one main document for new contributors.

created a contributing document that explain all the simple steps to contribute to matplotlib
- how to fork, clone the git repository.
- how to install from source
- how to run the tests
- how to create a PR and contributions guidelines
coding_guide has been split into contribution guidelines (in the documentation aforementionned) and reviewers guidelines
Removed transformation.rst and "hid" the license discussion documentation (which IMO should be removed and replace by a link to Jake V.'s blogpost on that matter).

What is left to be done

Improve the stylesheet for notes
Improve the content of "The Matplotlib Developers’ Guide"
- Split the content into three parts: contributor, reviewer, releaser.
- Reorder the contents so that it is (1) the main contribution guidelines; (2) documenting mpl; (3) testing mpl; (4) More information on the git workflow; (5) the rest?
add the new "new-contributor-friendly" tag.

Open questions

Should the "color change" file exist? The information in that file should probably be moved to a MEP
Should we keep the file "documenting matplotlib"? Most of it is out of date or already documented in sphinx.

An overview of the current documentation can be seen here: http://cbio.mines-paristech.fr/~nvaroquaux/tmp/matplotlib/devel/contributing.html

closes #7234

NelleV · 2016-10-11T00:15:21Z

hi @choldgraf
That's the PR I was talking about. Any feedback is welcomed.

NelleV · 2016-10-11T01:39:19Z

A recent build of the documentation is here: http://cbio.mines-paristech.fr/~nvaroquaux/tmp/matplotlib/devel/contributing.html

Any feedback is welcomed.

tacaswell · 2016-10-11T01:48:15Z

doc/devel/contributing.rst

+ 2. Fork the `project repository
+    <https://github.com/matplotlib/matplotlib>`__: click on the 'Fork' button
+    near the top of the page. This creates a copy of the code under your
+    account scikit-learnon the GitHub server.


scikit-learn reference left.

tacaswell · 2016-10-11T01:49:21Z

doc/devel/contributing.rst

+      import matplotlib.collections as mcol
+      import matplotlib.patches as mpatches
+
+  * If your changes are non-trivial, please make an entry in the


We do not maintain the CHANGELOG anymore

tacaswell · 2016-10-11T01:50:26Z

doc/devel/contributing.rst

+    :file:`CHANGELOG`.
+
+  * If your change is a major new feature, add an entry to
+    :file:`doc/users/whats_new.rst`.


ask to create a file in doc/user/what_new (and see the README in that folder. This greatly reduces merge conflicts. The files are all merged periodically.

tacaswell · 2016-10-11T01:50:51Z

doc/devel/contributing.rst

+  * If your change is a major new feature, add an entry to
+    :file:`doc/users/whats_new.rst`.
+
+  * If you change the API in a backward-incompatible way, please


ditto for putting in the doc/api/api_changes folder.

tacaswell · 2016-10-11T01:51:11Z

doc/devel/contributing.rst

+    document it in :file:`doc/api/api_changes.rst`.
+
+
+  * Adding a new pyplot function involves generating code.  See


lets not extend the pyplot inteface....

tacaswell · 2016-10-11T01:55:09Z

doc/devel/reviewers_guide.rst

+* In general, simple bugfixes that are unlikely to introduce new bugs
+  of their own should be merged onto the maintenance branch.  New
+  features, or anything that changes the API, should be made against
+  master.  The rules are fuzzy here -- when in doubt, try to get some


I would say 'when in doubt, target master'

tacaswell · 2016-10-11T01:57:43Z

I am 50/50 on renaming the rst files. The new names are better, but they are going to break somebodys bookmark.

tacaswell · 2016-10-11T01:59:30Z

doc/devel/index.rst


-   coding_guide.rst
-   portable_code.rst
-   license.rst


I would leave this.

Are you talking about the license.rst? It doesn't really fit in the developers section. There is currently a link to it somewhere in the user documentation.

Yes, but if it is still linked to via a visible link, then ignore my comment.

NelleV · 2016-10-11T04:14:25Z

@tacaswell good point about the bookmarks. I hadn't thought about this. I'll revert back to the old names.

NelleV · 2016-10-12T04:04:47Z

I've addressed @tacaswell's comment (a refresher was clearer a good idea!)
and rebased onto master (thus integrating the PR on setting up matplotlib).

I still have to add the new contributor tag.

NelleV · 2016-10-12T04:36:56Z

I've added a section about the new-contibutor-friendly tag and the easy-fix tag and made some changes to the style.

I am still not convinced that the new-contributor-friendly tag adds more to the table than the easy-fix one. we'll have to see long run whether it is worth having both.

A fresh build of the documentation is available here:
http://cbio.mines-paristech.fr/~nvaroquaux/tmp/matplotlib/devel/contributing.html

efiring

Comments and corrections are mostly minor.

efiring · 2016-10-12T06:49:09Z

doc/devel/contributing.rst

+In case you experience issues using this package, do not hesitate to submit a
+ticket to the
+`Bug Tracker <https://github.com/matplotlib/matplotlib/issues>`_. You are
+also welcome to post feature requests or pull requests.


Is it worth adding something about the matplotlib-users mailing list, encouraging its use for "how do I do..." and "why does matplotlib do this" questions?

Especially if we continue with "experience issues", then it's even more prudent to mention it.

efiring · 2016-10-12T06:51:18Z

doc/devel/contributing.rst

+Submitting a bug report
+=======================
+
+In case you experience issues using this package, do not hesitate to submit a


"In case you experience issues" -> "If you find a bug in the code or documentation"

efiring · 2016-10-12T06:54:00Z

doc/devel/contributing.rst

+
+
+After obtaining a local copy of the matpotlib source code (:ref:`set-up-fork`),
+navigate to the matplotlib directory and run the following in the shell:


I like to make sure I don't have any version of matplotlib already installed in whatever location I am about to install the development version. Is it worth making a recommendation like this?

Yes, it is definitely worth it.
I think it might be interesting to have a FAQ of common encountered problems with setting up working environments with matplotlib. This is one of the problem my students encountered, and the other problem being the tests massively failing.

efiring · 2016-10-12T06:55:14Z

doc/devel/contributing.rst

+   pip install -v -e .
+
+This installs matplotlib for development (i.e., builds everything and places the
+symbolic links back to the source code). You can then run the tests your work


"tests your work" -> "tests to check that your work"

efiring · 2016-10-12T06:57:31Z

doc/devel/contributing.rst

+symbolic links back to the source code). You can then run the tests your work
+environment is set up properly::
+
+  python tests.py


If this is run at this stage it will spew image comparison failures, won't it? Maybe better to delay all mention of running the test until the place below where you tell how to set things up for testing.

On my computer, it works fine at this stage. I am lucky?

It's not strictly problematic, but if you don't tell it to use the fixed version of freetype, you might run into a lot of image failures if all the text has shifted a bit (like say, the next versions of Debian and Fedora, which include a newer FreeType.)

efiring · 2016-10-12T07:27:50Z

doc/devel/contributing.rst

+  code.  The interface code should be named `FOO_wrap.cpp` or
+  `FOO_wrapper.cpp`.
+
+* Header file documentation (aka docstrings) should be in Numpydoc


I don't understand this bullet point at all.

eh… me neither…
I could just remove it?

Presumably this is about docstrings that live inside C/C++ code... Like this resample docstring. I would just change it to "Docstrings should be in Numpydoc..." - since this is already under the C/C++ extensions header.

I am in favor of leaving this section as is (but maybe burying it a but further down the page).

efiring · 2016-10-12T07:28:52Z

doc/devel/contributing.rst

+
+Matplotlib makes extensive use of ``**kwargs`` for pass-through
+customizations from one function to another.  A typical example is in
+:func:`matplotlib.pylab.text`.  The definition of the pylab text


pylab -> pyplot

efiring · 2016-10-12T07:29:48Z

doc/devel/contributing.rst

+i.e., it just passes all ``args`` and ``kwargs`` on to
+:meth:`matplotlib.text.Text.__init__`::
+
+  # in axes.py


axes/_axes.py

efiring · 2016-10-12T07:31:24Z

doc/devel/contributing.rst

+local arguments and the rest are passed on as
+:meth:`~matplotlib.lines.Line2D` keyword arguments::
+
+  # in axes.py


axes/_axes.py

efiring · 2016-10-12T07:33:27Z

doc/devel/contributing.rst

+:file:`matplotlibrc` (:ref:`customizing-matplotlib`) supports an
+external backend via the ``module`` directive.  if
+:file:`my_backend.py` is a matplotlib backend in your
+:envvar:`PYTHONPATH`, you can set use it on one of several ways


delete "use"? or delete "set"?
All of the following looks like it might be replaced with a link to somewhere else in the docs.

efiring · 2016-10-12T18:49:12Z

On 2016/10/12 8:12 AM, Nelle Varoquaux wrote:

On my computer, it works fine at this stage. I am lucky?

I think it means you just happen to have the right version of freetype
installed.

QuLogic

There were a few more comments than I expected; I might just commit some parts directly if you're fine with it.

QuLogic · 2016-10-12T22:55:45Z

doc/_static/mpl.css


+div.warning {
+    color: #b94a48;
+    background-color: #F3E5E5;


The added colours are in varying case.

QuLogic · 2016-10-12T22:57:52Z

doc/_static/mpl.css

+    margin-top: 10px;
+    padding: 7px;
+    border-radius: 4px;
+    -moz-border-radius: 4px;


Did you write this yourself, or is it generated somehow? Why only add the -moz prefix? It seems like border-radius was standardized a long long time ago.

It's from the nature stylesheet of sphinx.

Ah, I see. I guess they just haven't updated them in a while.

QuLogic · 2016-10-12T22:58:11Z

doc/devel/add_new_projection.rst

-Adding new scales and projections to matplotlib
-***********************************************
+========================================================
+Developer's guide for creating scales and transformation


transformations

QuLogic · 2016-10-12T22:58:53Z

doc/devel/coding_guide.rst

-************
-Coding guide
-************
+********************


Reviewer's

Also, I think there's one extra asterisk here.

QuLogic · 2016-10-12T23:03:17Z

doc/devel/contributing.rst

+In case you experience issues using this package, do not hesitate to submit a
+ticket to the
+`Bug Tracker <https://github.com/matplotlib/matplotlib/issues>`_. You are
+also welcome to post feature requests or pull requests.


Especially if we continue with "experience issues", then it's even more prudent to mention it.

QuLogic · 2016-10-12T23:29:32Z

doc/devel/contributing.rst

+Note: there is a use case when ``kwargs`` are meant to be used locally
+in the function (not passed on), but you still need the ``**kwargs``
+idiom.  That is when you want to use ``*args`` to allow variable
+numbers of non-keyword args.  In this case, python will not allow you


Is that common? It seems like something that's mostly an artifact of Matlab's designs.

And we mirrored that API very closely at the beginning. There is probably a few more cases (but I do not know any off the top of my head).

This should have a comment added that this is only a python2 restriction, as soon as we drop 2.7 as supported we can use keyword-only arguments 😄 (that is the python3 feature I like the most).

QuLogic · 2016-10-12T23:33:01Z

doc/devel/contributing.rst

+----------------
+
+We have hundreds of examples in subdirectories of
+:file:`matplotlib/examples`, and these are automatically generated


"these" is ambiguous; it sounds like the examples are automatically generated, but it's really their outputs that are automatically generated.

QuLogic · 2016-10-12T23:33:34Z

doc/devel/gitwash/development_workflow.rst

-====================
+=========================
+Git Development workflow
+=========================


Looks like an extra =?

QuLogic · 2016-10-12T23:33:47Z

doc/devel/portable_code.rst

+.. _portable_code:
+
+=====================================================
+Developer's tips for writing code for python 2 and 3


QuLogic · 2016-10-12T23:34:12Z

doc/devel/testing.rst


  - nose_, version 1.0 or later
-
  - `mock <http://www.voidspace.org.uk/python/mock/>`_, when running python


See above comments, but these links might be outdated.

dopplershift

edited Oh, I see now I was only seeing the latest set of changes and commenting on them.

dopplershift · 2016-10-13T21:39:47Z

doc/devel/contributing.rst

+
+
+.. _nose: https://nose.readthedocs.org/en/latest/
+.. _pep8: https://pep8.readthedocs.org/en/latest/


Since you're updating these URLs, would this be a good time to move to readthedocs.io? (See here)

What do you mean by this? Move the matplotlib documentation to readthedocs.io?

oh… I just understood :)

dopplershift · 2016-10-13T21:40:28Z

doc/devel/contributing.rst

 Matplotlib makes extensive use of ``**kwargs`` for pass-through
 customizations from one function to another.  A typical example is in
-:func:`matplotlib.pylab.text`.  The definition of the pylab text
+:func:`matplotlib.pyplot.text`.  The definition of the pylab text


Would it make sense to change pylab to pyplot in the text as well?

yep… I actually think that we may want to do a git grep pylab on the whole project and check individually whether to move it to pyplot. It's on my todo list.

dopplershift · 2016-10-13T21:40:44Z

doc/devel/testing.rst

 please ignore it while we consolidate our testing to these locations.)

-.. _nose: http://nose.readthedocs.org/en/latest/
+.. _nose: https://nose.readthedocs.org/en/latest/


Again about RTD.

NelleV · 2016-10-14T23:39:48Z

@dopplershift I git grepped the code for readthedocs.org urls to replace them with the new io ones. The matplotlib documentation should be rtd.org free.

QuLogic · 2016-10-15T03:43:40Z

examples/axisartist/demo_parasite_axes2.py

    par2.set_ylabel("Velocity")

-    p1, = host.plot([0, 1, 2], [0, 1, 2], label="Density")
+    p1, = par1.plot([0, 1, 2], [0, 1, 2], label="Density")


Was that supposed to change in this commit? (It's the rtd.org -> rtd.io commit.)

that was a mistake. I'll revert it.

dopplershift · 2016-10-16T02:52:28Z

Sweet, thanks for going ahead with that!

NelleV · 2016-10-17T22:19:18Z

I think this is ready to be merged.

NelleV · 2016-10-18T21:51:53Z

@ivanov was interested in giving feedback on this pull request.
I'll rebase in the mean time.

ivanov · 2016-10-19T05:27:28Z

👍 - I wasn't sure why readthedocs links were changed from .org to point to .io, so I looked it up and found this explanation (in case anyone else ends up wondering about that the way I did)

NelleV · 2016-10-25T14:04:07Z

Is there anything else to be done on this PR for it to be merged?

closes #7234

* DOC adressed reviewer's comments * DOC rdt.org -> rdt.io

choldgraf · 2016-11-02T19:15:15Z

FWIW, I'm trying to get up-to-speed on how to contribute to matplotlib, and this PR would be helpful for somebody in my position. It looks like this is close to being ready to go, looking forward to seeing some updated docs

ivanov · 2016-11-02T23:01:18Z

There's one failure on Travis, which is unrelated, since this PR does not introduce any code changes. (for reference - the failure's test_invisible_Line_rendering)

I'm going to go ahead and merge this one, and we can iterate further. Good work everyone, especially @NelleV !

Happy hacking!

choldgraf · 2016-11-02T23:06:13Z

🍻

ENH Improving the contribution guidelines

ivanov · 2016-11-02T23:13:56Z

backported to v2.x in 28f4b6e

ivanov · 2016-11-02T23:16:01Z

(oops, had the wrong SHA in github comment above, fixed it now - it's 28f4b6e )

NelleV · 2016-11-02T23:19:06Z

Thanks @ivanov ! And welcome back :)

mdboom added the status: needs review label Oct 8, 2016

NelleV added the Documentation label Oct 8, 2016

NelleV changed the title ~~[WIP] ENH Improving the contribution guidelines~~ [MRG] ENH Improving the contribution guidelines Oct 11, 2016

tacaswell reviewed Oct 11, 2016

View reviewed changes

tacaswell mentioned this pull request Oct 11, 2016

DOC: instructions on installing matplotlib for dev #7229

Merged

tacaswell modified the milestone: 2.0.1 (next bug fix release) Oct 11, 2016

efiring requested changes Oct 12, 2016

View reviewed changes

NelleV added status: needs revision and removed status: needs review labels Oct 12, 2016

QuLogic reviewed Oct 12, 2016

View reviewed changes

NelleV added status: needs review and removed status: needs revision labels Oct 13, 2016

dopplershift approved these changes Oct 13, 2016

View reviewed changes

QuLogic reviewed Oct 15, 2016

View reviewed changes

tacaswell changed the title ~~[MRG] ENH Improving the contribution guidelines~~ [MRG+1] ENH Improving the contribution guidelines Oct 29, 2016

tacaswell approved these changes Oct 29, 2016

View reviewed changes

NelleV added 13 commits October 29, 2016 15:08

ENH contributing guidelines are now all in one place

d00c927

ENH Improved contributing documentation

419ce52

closes #7234

DOC remove transformation.rst and hide license doc

0b9974c

FIX typo

085844a

DOC improved organization and titles

9799d66

ENH better styling for notes, warnings and see also section

9547bc7

DOC Better crosslinking of dev references

5a9f988

DOC better title

c97d6ac

DOC no more addition to pyplot

54e0c9c

DOC fixes to the reviewer's guide

76a5ab2

DOC added easy-fix and new-contributor-friendly tags

19603a5

DOC better styling for topic sections

388a4a0

* DOC adressed reviewer's comments * DOC rdt.org -> rdt.io

DOC Transformations are now documented in the API

4d8963f

story645 mentioned this pull request Nov 2, 2016

Updating the readme #7381

Merged

ivanov merged commit 5ac0881 into matplotlib:master Nov 2, 2016

ivanov added a commit that referenced this pull request Nov 2, 2016

Merge pull request #7236 from NelleV/enh_contributing_guidelines

28f4b6e

ENH Improving the contribution guidelines

QuLogic removed the status: needs review label Nov 2, 2016

QuLogic changed the title ~~[MRG+1] ENH Improving the contribution guidelines~~ ENH Improving the contribution guidelines Dec 7, 2016

QuLogic modified the milestones: 2.0.1 (next bug fix release), 2.0 (style change major release) Dec 7, 2016

		document it in :file:`doc/api/api_changes.rst`.


		* Adding a new pyplot function involves generating code. See



		After obtaining a local copy of the matpotlib source code (:ref:`set-up-fork`),
		navigate to the matplotlib directory and run the following in the shell:


		- nose_, version 1.0 or later

		- `mock <http://www.voidspace.org.uk/python/mock/>`_, when running python



		.. _nose: https://nose.readthedocs.org/en/latest/
		.. _pep8: https://pep8.readthedocs.org/en/latest/

Uh oh!

Conversation

NelleV commented Oct 8, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

NelleV commented Oct 11, 2016

Uh oh!

NelleV commented Oct 11, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tacaswell Oct 11, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tacaswell commented Oct 11, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

NelleV commented Oct 11, 2016

Uh oh!

NelleV commented Oct 12, 2016

Uh oh!

NelleV commented Oct 12, 2016

Uh oh!

efiring left a comment

Choose a reason for hiding this comment

Uh oh!

efiring Oct 12, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

efiring Oct 12, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

NelleV commented Oct 8, 2016 •

edited

Loading

tacaswell Oct 11, 2016 •

edited

Loading

efiring Oct 12, 2016 •

edited

Loading

efiring Oct 12, 2016 •

edited

Loading