<divid="unreleased-message"> You are reading an old version of the documentation (v2.1.2). For the latest version see <ahref="https://matplotlib.org/stable/devel/contributing.html">https://matplotlib.org/stable/devel/contributing.html</a></div>
<li><aclass="reference internal" href="#submitting-a-bug-report">Submitting a bug report</a></li>
<li><aclass="reference internal" href="#retrieving-and-installing-the-latest-version-of-the-code">Retrieving and installing the latest version of the code</a><ul>
<li><aclass="reference internal" href="#building-matplotlib-for-image-comparison-tests">Building Matplotlib for image comparison tests</a></li>
<li><aclass="reference internal" href="#installing-matplotlib-in-developer-mode">Installing Matplotlib in developer mode</a></li>
<spanid="id1"></span><h1>Contributing<aclass="headerlink" href="#contributing" title="Permalink to this headline">¶</a></h1>
<p>This project is a community effort, and everyone is welcome to
contribute.</p>
<p>The project is hosted on <aclass="reference external" href="https://github.com/matplotlib/matplotlib">https://github.com/matplotlib/matplotlib</a></p>
<divclass="section" id="submitting-a-bug-report">
<h2>Submitting a bug report<aclass="headerlink" href="#submitting-a-bug-report" title="Permalink to this headline">¶</a></h2>
<p>If you find a bug in the code or documentation, do not hesitate to submit a
ticket to the
<aclass="reference external" href="https://github.com/matplotlib/matplotlib/issues">Bug Tracker</a>. You are also
welcome to post feature requests or pull requests.</p>
<p>If you are reporting a bug, please do your best to include the following:</p>
<olclass="arabic">
<li><pclass="first">A short, top-level summary of the bug. In most cases, this should be 1-2
sentences.</p>
</li>
<li><pclass="first">A short, self-contained code snippet to reproduce the bug, ideally allowing
a simple copy and paste to reproduce. Please do your best to reduce the code
snippet to the minimum required.</p>
</li>
<li><pclass="first">The actual outcome of the code snippet.</p>
</li>
<li><pclass="first">The expected outcome of the code snippet.</p>
</li>
<li><pclass="first">The Matplotlib version, Python version and platform that you are using. You
can grab the version with the following commands:</p>
<spanid="installing-for-devs"></span><h2>Retrieving and installing the latest version of the code<aclass="headerlink" href="#retrieving-and-installing-the-latest-version-of-the-code" title="Permalink to this headline">¶</a></h2>
<p>When developing Matplotlib, sources must be downloaded, built, and installed into
a local environment on your machine.</p>
<p>Follow the instructions detailed <aclass="reference internal" href="../users/installing.html#install-from-source"><spanclass="std std-ref">here</span></a> to set up your
environment to build Matplotlib from source.</p>
<divclass="admonition warning">
<pclass="first admonition-title">Warning</p>
<pclass="last">When working on Matplotlib sources, having multiple versions installed by
different methods into the same environment may not always work as expected.</p>
</div>
<p>To work on Matplotlib sources, it is strongly recommended to set up an alternative
development environment, using the something like <aclass="reference external" href="http://docs.python-guide.org/en/latest/dev/virtualenvs/">virtual environments in python</a>, or a
<p>and navigate to the <codeclass="file docutils literal"><spanclass="pre">matplotlib</span></code> directory. If you have the proper privileges,
you can use <codeclass="docutils literal"><spanclass="pre">git@</span></code> instead of <codeclass="docutils literal"><spanclass="pre">https://</span></code>, which works through the ssh protocol
and might be easier to use if you are using 2-factor authentication.</p>
<h3>Building Matplotlib for image comparison tests<aclass="headerlink" href="#building-matplotlib-for-image-comparison-tests" title="Permalink to this headline">¶</a></h3>
<p>Matplotlib’s test suite makes heavy use of image comparison tests,
meaning the result of a plot is compared against a known good result.
Unfortunately, different versions of FreeType produce differently
formed characters, causing these image comparisons to fail. To make
them reproducible, Matplotlib can be built with a special local copy
of FreeType. This is recommended for all Matplotlib developers.</p>
<p>Copy <codeclass="file docutils literal"><spanclass="pre">setup.cfg.template</span></code> to <codeclass="file docutils literal"><spanclass="pre">setup.cfg</span></code> and edit it to contain:</p>
<h3>Installing Matplotlib in developer mode<aclass="headerlink" href="#installing-matplotlib-in-developer-mode" title="Permalink to this headline">¶</a></h3>
<p>To install Matplotlib (and compile the c-extensions) run the following
<h3>Contributing pull requests<aclass="headerlink" href="#contributing-pull-requests" title="Permalink to this headline">¶</a></h3>
<p>It is recommended to check that your contribution complies with the following
rules before submitting a pull request:</p>
<ul>
<li><pclass="first">If your pull request addresses an issue, please use the title to describe the
issue and mention the issue number in the pull request description to ensure
that a link is created to the original issue.</p>
</li>
<li><pclass="first">All public methods should have informative docstrings with sample usage when
appropriate. Use the <aclass="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html">numpy docstring standard</a>.</p>
</li>
<li><pclass="first">Formatting should follow the recommendations of <aclass="reference external" href="https://www.python.org/dev/peps/pep-0008/">PEP8</a>. You should consider
installing/enabling automatic PEP8 checking in your editor. Part of the test
suite is checking PEP8 compliance, things go smoother if the code is mostly
PEP8 compliant to begin with.</p>
</li>
<li><pclass="first">Each high-level plotting function should have a simple example in the
<codeclass="docutils literal"><spanclass="pre">Example</span></code> section of the docstring. This should be as simple as possible
to demonstrate the method. More complex examples should go in the
<li><pclass="first">Changes (both new features and bugfixes) should be tested. See <aclass="reference internal" href="testing.html#testing"><spanclass="std std-ref">Developer’s tips for testing</span></a>
for more details.</p>
</li>
<li><pclass="first">Import the following modules using the standard scipy conventions:</p>
<li><pclass="first">If your change is a major new feature, add an entry to the <codeclass="docutils literal"><spanclass="pre">What's</span><spanclass="pre">new</span></code>
section by adding a new file in <codeclass="docutils literal"><spanclass="pre">doc/users/next_whats_new</span></code> (see
<codeclass="file docutils literal"><spanclass="pre">doc/users/next_whats_new/README.rst</span></code> for more information).</p>
</li>
<li><pclass="first">If you change the API in a backward-incompatible way, please document it in
<codeclass="xref py py-obj docutils literal"><spanclass="pre">doc/api/api_changes</span></code>, by adding a new file describing your changes (see
<codeclass="file docutils literal"><spanclass="pre">doc/api/api_changes/README.rst</span></code> for more information)</p>
</li>
<li><pclass="first">See below for additional points about <aclass="reference internal" href="#keyword-argument-processing"><spanclass="std std-ref">Keyword argument processing</span></a>, if
applicable for your pull request.</p>
</li>
</ul>
<p>In addition, you can check for common programming errors with the following
tools:</p>
<ul>
<li><pclass="first">Code with a good unittest coverage (at least 70%, better 100%), check with:</p>
<spanid="new-contributors"></span><h3>Issues for New Contributors<aclass="headerlink" href="#issues-for-new-contributors" title="Permalink to this headline">¶</a></h3>
<p>New contributors should look for the following tags when looking for issues.
We strongly recommend that new contributors tackle
<spanid="id4"></span><h3>Keyword argument processing<aclass="headerlink" href="#keyword-argument-processing" title="Permalink to this headline">¶</a></h3>
<p>Matplotlib makes extensive use of <codeclass="docutils literal"><spanclass="pre">**kwargs</span></code> for pass-through
customizations from one function to another. A typical example is in
<aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.text.html#matplotlib.pyplot.text" title="matplotlib.pyplot.text"><codeclass="xref py py-func docutils literal"><spanclass="pre">matplotlib.pyplot.text()</span></code></a>. The definition of the pylab text
<p><aclass="reference internal" href="../api/_as_gen/matplotlib.axes.Axes.text.html#matplotlib.axes.Axes.text" title="matplotlib.axes.Axes.text"><codeclass="xref py py-meth docutils literal"><spanclass="pre">text()</span></code></a> in simplified form looks like this,
i.e., it just passes all <codeclass="docutils literal"><spanclass="pre">args</span></code> and <codeclass="docutils literal"><spanclass="pre">kwargs</span></code> on to
<p><codeclass="docutils literal"><spanclass="pre">update</span></code> does the work looking for methods named like
<codeclass="docutils literal"><spanclass="pre">set_property</span></code> if <codeclass="docutils literal"><spanclass="pre">property</span></code> is a keyword argument. i.e., no one
looks at the keywords, they just get passed through the API to the
artist constructor which looks for suitably named methods and calls
them with the value.</p>
<p>As a general rule, the use of <codeclass="docutils literal"><spanclass="pre">**kwargs</span></code> should be reserved for
pass-through keyword arguments, as in the example above. If all the
keyword args are to be used in the function, and not passed
on, use the key/value keyword args in the function definition rather
than the <codeclass="docutils literal"><spanclass="pre">**kwargs</span></code> idiom.</p>
<p>In some cases, you may want to consume some keys in the local
function, and let others pass through. You can <codeclass="docutils literal"><spanclass="pre">pop</span></code> the ones to be
used locally and pass on the rest. For example, in
<aclass="reference internal" href="../api/_as_gen/matplotlib.axes.Axes.plot.html#matplotlib.axes.Axes.plot" title="matplotlib.axes.Axes.plot"><codeclass="xref py py-meth docutils literal"><spanclass="pre">plot()</span></code></a>, <codeclass="docutils literal"><spanclass="pre">scalex</span></code> and <codeclass="docutils literal"><spanclass="pre">scaley</span></code> are
<spanid="custom-backend"></span><h3>Developing a new backend<aclass="headerlink" href="#developing-a-new-backend" title="Permalink to this headline">¶</a></h3>
<p>If you are working on a custom backend, the <em>backend</em> setting in
<codeclass="file docutils literal"><spanclass="pre">matplotlibrc</span></code> (<aclass="reference internal" href="../tutorials/introductory/customizing.html#sphx-glr-tutorials-introductory-customizing-py"><spanclass="std std-ref">Customizing matplotlib</span></a>) supports an
external backend via the <codeclass="docutils literal"><spanclass="pre">module</span></code> directive. If
<codeclass="file docutils literal"><spanclass="pre">my_backend.py</span></code> is a Matplotlib backend in your
<spanclass="target" id="index-0"></span><aclass="reference internal" href="../faq/environment_variables_faq.html#envvar-PYTHONPATH"><codeclass="xref std std-envvar docutils literal"><spanclass="pre">PYTHONPATH</span></code></a>, you can set it on one of several ways</p>
<spanid="sample-data"></span><h3>Writing examples<aclass="headerlink" href="#writing-examples" title="Permalink to this headline">¶</a></h3>
<p>We have hundreds of examples in subdirectories of
<codeclass="file docutils literal"><spanclass="pre">matplotlib/examples</span></code>, and these are automatically generated
when the website is built to show up in the <codeclass="xref py py-obj docutils literal"><spanclass="pre">examples</span></code> section of the website.</p>
<p>Any sample data that the example uses should be kept small and
distributed with Matplotlib in the
<codeclass="xref py py-obj docutils literal"><spanclass="pre">lib/matplotlib/mpl-data/sample_data/</span></code> directory. Then in your
example code you can load it into a file handle with:</p>