Skip to content

ENH Improving the contribution guidelines - #7236

Merged
ivanov merged 13 commits into
matplotlib:masterfrom
NelleV:enh_contributing_guidelines
Nov 2, 2016
Merged

ivanov merged 13 commits into
matplotlib:masterfrom
NelleV:enh_contributing_guidelines

Conversation

@NelleV

@NelleV NelleV commented Oct 8, 2016 •

Copy link
Copy Markdown
Member

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

NelleV commented Oct 11, 2016

Copy link
Copy Markdown
Member Author

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

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

NelleV commented Oct 11, 2016

Copy link
Copy Markdown
Member Author

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

Any feedback is welcomed.

Comment thread doc/devel/contributing.rst Outdated
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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

scikit-learn reference left.

Comment thread doc/devel/contributing.rst Outdated
import matplotlib.collections as mcol
import matplotlib.patches as mpatches

* If your changes are non-trivial, please make an entry in the

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

We do not maintain the CHANGELOG anymore

Comment thread doc/devel/contributing.rst Outdated
:file:`CHANGELOG`.

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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.

* 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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

Comment thread doc/devel/contributing.rst Outdated
document it in :file:`doc/api/api_changes.rst`.


* Adding a new pyplot function involves generating code. See

@tacaswell tacaswell Oct 11, 2016 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

lets not extend the pyplot inteface....

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

👍

Comment thread doc/devel/reviewers_guide.rst Outdated
* 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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I would say 'when in doubt, target master'

@tacaswell

Copy link
Copy Markdown
Member

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

Comment thread doc/devel/index.rst

coding_guide.rst
portable_code.rst
license.rst

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I would leave this.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Yes, it is

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

NelleV commented Oct 11, 2016

Copy link
Copy Markdown
Member Author

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

@NelleV

NelleV commented Oct 12, 2016

Copy link
Copy Markdown
Member Author

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

NelleV commented Oct 12, 2016

Copy link
Copy Markdown
Member Author

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 efiring left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Comments and corrections are mostly minor.

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.

@efiring efiring Oct 12, 2016 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

Comment thread doc/devel/contributing.rst Outdated
Submitting a bug report
=======================

In case you experience issues using this package, do not hesitate to submit a

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

Comment thread doc/devel/contributing.rst Outdated


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:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

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.

Comment thread doc/devel/contributing.rst Outdated
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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

Comment thread doc/devel/contributing.rst Outdated
symbolic links back to the source code). You can then run the tests your work
environment is set up properly::

python tests.py

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

code. The interface code should be named `FOO_wrap.cpp` or
`FOO_wrapper.cpp`.

* Header file documentation (aka docstrings) should be in Numpydoc

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I don't understand this bullet point at all.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

eh… me neither…
I could just remove it?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

Comment thread doc/devel/contributing.rst Outdated

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

pylab -> pyplot

Comment thread doc/devel/contributing.rst Outdated
i.e., it just passes all ``args`` and ``kwargs`` on to
:meth:`matplotlib.text.Text.__init__`::

# in axes.py

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

axes/_axes.py

Comment thread doc/devel/contributing.rst Outdated
local arguments and the rest are passed on as
:meth:`~matplotlib.lines.Line2D` keyword arguments::

# in axes.py

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

axes/_axes.py

Comment thread doc/devel/contributing.rst Outdated
: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

@efiring efiring Oct 12, 2016 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

efiring commented Oct 12, 2016

Copy link
Copy Markdown
Member

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 QuLogic left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

Comment thread doc/_static/mpl.css

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

The added colours are in varying case.

Comment thread doc/_static/mpl.css
margin-top: 10px;
padding: 7px;
border-radius: 4px;
-moz-border-radius: 4px;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

It's from the nature stylesheet of sphinx.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

Comment thread doc/devel/add_new_projection.rst Outdated
Adding new scales and projections to matplotlib
***********************************************
========================================================
Developer's guide for creating scales and transformation

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

transformations

************
Coding guide
************
********************

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Reviewer's

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

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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

----------------

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

====================
=========================
Git Development workflow
=========================

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Looks like an extra =?

Comment thread doc/devel/portable_code.rst Outdated
.. _portable_code:

=====================================================
Developer's tips for writing code for python 2 and 3

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Python

Comment thread doc/devel/testing.rst Outdated

- nose_, version 1.0 or later

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

See above comments, but these links might be outdated.

@dopplershift dopplershift left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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

Comment thread doc/devel/contributing.rst Outdated


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

@dopplershift dopplershift Oct 13, 2016 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

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

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

oh… I just understood :)

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

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.

Comment thread doc/devel/testing.rst Outdated
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/

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Again about RTD.

@NelleV

NelleV commented Oct 14, 2016

Copy link
Copy Markdown
Member Author

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

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

@QuLogic QuLogic Oct 15, 2016 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

that was a mistake. I'll revert it.

@dopplershift

Copy link
Copy Markdown
Contributor

Sweet, thanks for going ahead with that!

@NelleV

NelleV commented Oct 17, 2016

Copy link
Copy Markdown
Member Author

I think this is ready to be merged.

@NelleV

NelleV commented Oct 18, 2016

Copy link
Copy Markdown
Member Author

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

@ivanov

ivanov commented Oct 19, 2016

Copy link
Copy Markdown
Member

👍 - 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

NelleV commented Oct 25, 2016

Copy link
Copy Markdown
Member Author

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

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

Copy link
Copy Markdown
Contributor

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

@story645 story645 mentioned this pull request Nov 2, 2016
@ivanov

ivanov commented Nov 2, 2016

Copy link
Copy Markdown
Member

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! :bowtie:

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

Copy link
Copy Markdown
Contributor

🍻

ivanov added a commit that referenced this pull request Nov 2, 2016
ENH Improving the contribution guidelines
@ivanov

ivanov commented Nov 2, 2016 •

Copy link
Copy Markdown
Member

backported to v2.x in 28f4b6e

@ivanov

ivanov commented Nov 2, 2016

Copy link
Copy Markdown
Member

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

@NelleV

NelleV commented Nov 2, 2016

Copy link
Copy Markdown
Member Author

Thanks @ivanov ! And welcome back :)

@QuLogic QuLogic changed the title [MRG+1] ENH Improving the contribution guidelines ENH Improving the contribution guidelines Dec 7, 2016
@QuLogic QuLogic modified the milestones: 2.0.1 (next bug fix release), 2.0 (style change major release) Dec 7, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improving documentation: Tests failing on a osx setup

9 participants