<divid="unreleased-message"> You are reading an old version of the documentation (v2.2.4). 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 notranslate"><spanclass="pre">matplotlib</span></code> directory. If you have the proper privileges,
you can use <codeclass="docutils literal notranslate"><spanclass="pre">git@</span></code> instead of <codeclass="docutils literal notranslate"><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 notranslate"><spanclass="pre">setup.cfg.template</span></code> to <codeclass="file docutils literal notranslate"><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
<li><aclass="reference internal" href="testing.html#testing"><spanclass="std std-ref">Developer's tips for testing</span></a></li>
</ul>
</div>
</div>
</div>
<divclass="section" id="contributing-code">
<h2>Contributing code<aclass="headerlink" href="#contributing-code" title="Permalink to this headline">¶</a></h2>
<divclass="section" id="how-to-contribute">
<h3>How to contribute<aclass="headerlink" href="#how-to-contribute" title="Permalink to this headline">¶</a></h3>
<p>The preferred way to contribute to Matplotlib is to fork the <aclass="reference external" href="https://github.com/matplotlib/matplotlib/">main
repository</a> on GitHub,
then submit a "pull request" (PR).</p>
<p>The best practices for using GitHub to make PRs to Matplotlib are
documented in the <aclass="reference internal" href="gitwash/development_workflow.html#development-workflow"><spanclass="std std-ref">Development workflow</span></a> section.</p>
<p>A brief overview is:</p>
<olclass="arabic">
<li><pclass="first"><aclass="reference external" href="https://github.com/join">Create an account</a> on GitHub if you do not
already have one.</p>
</li>
<li><pclass="first">Fork the <aclass="reference external" href="https://github.com/matplotlib/matplotlib">project repository</a>:
click on the 'Fork' button near the top of the page. This creates a copy of
the code under your account on the GitHub server.</p>
</li>
<li><pclass="first">Clone this copy to your local disk:</p>
<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 notranslate"><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 notranslate"><spanclass="pre">What's</span><spanclass="pre">new</span></code>
section by adding a new file in <codeclass="docutils literal notranslate"><spanclass="pre">doc/users/next_whats_new</span></code> (see
<codeclass="file docutils literal notranslate"><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 notranslate"><spanclass="pre">doc/api/api_changes</span></code>, by adding a new file describing your changes (see
<codeclass="file docutils literal notranslate"><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 issues labeled
<aclass="reference external" href="https://github.com/matplotlib/matplotlib/labels/good%20first%20issue">good first issue</a>
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!</p>
<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 notranslate"><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 notranslate"><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 notranslate"><spanclass="pre">text()</span></code></a> in simplified form looks like this,
i.e., it just passes all <codeclass="docutils literal notranslate"><spanclass="pre">args</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">kwargs</span></code> on to
<p><codeclass="docutils literal notranslate"><spanclass="pre">update</span></code> does the work looking for methods named like
<codeclass="docutils literal notranslate"><spanclass="pre">set_property</span></code> if <codeclass="docutils literal notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><spanclass="pre">plot()</span></code></a>, <codeclass="docutils literal notranslate"><spanclass="pre">scalex</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">scaley</span></code> are
<spanid="using-logging"></span><h3>Using logging for debug messages<aclass="headerlink" href="#using-logging-for-debug-messages" title="Permalink to this headline">¶</a></h3>
<p>Matplotlib uses the standard python <aclass="reference external" href="https://docs.python.org/3/library/logging.html#module-logging" title="(in Python v3.7)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging</span></code></a> library to write verbose
warnings, information, and
debug messages. Please use it! In all those places you write <aclass="reference external" href="https://docs.python.org/3/library/functions.html#print" title="(in Python v3.7)"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">print()</span></code></a>
statements to do your debugging, try using <codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">log.debug()</span></code> instead!</p>
<p>To include <aclass="reference external" href="https://docs.python.org/3/library/logging.html#module-logging" title="(in Python v3.7)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging</span></code></a> in your module, at the top of the module, you need to
<codeclass="docutils literal notranslate"><spanclass="pre">import</span><spanclass="pre">logging</span></code>. Then calls in your code like:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="n">_log</span><spanclass="o">=</span><spanclass="n">logging</span><spanclass="o">.</span><spanclass="n">getLogger</span><spanclass="p">(</span><spanclass="vm">__name__</span><spanclass="p">)</span><spanclass="c1"># right after the imports</span>
<spanclass="c1"># code</span>
<spanclass="c1"># more code</span>
<spanclass="n">_log</span><spanclass="o">.</span><spanclass="n">info</span><spanclass="p">(</span><spanclass="s1">'Here is some information'</span><spanclass="p">)</span>
<spanclass="n">_log</span><spanclass="o">.</span><spanclass="n">debug</span><spanclass="p">(</span><spanclass="s1">'Here is some more detailed information'</span><spanclass="p">)</span>
</pre></div>
</div>
<p>will log to a logger named <codeclass="docutils literal notranslate"><spanclass="pre">matplotlib.yourmodulename</span></code>.</p>
<p>If an end-user of Matplotlib sets up <aclass="reference external" href="https://docs.python.org/3/library/logging.html#module-logging" title="(in Python v3.7)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging</span></code></a> to display at levels
more verbose than <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logger.WARNING</span></code> in their code as follows:</p>
are really only there for errors that will end the use of the library but
not kill the interpreter. <aclass="reference external" href="https://docs.python.org/3/library/logging.html#logging.warning" title="(in Python v3.7)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging.warning</span></code></a> overlaps with the
<codeclass="docutils literal notranslate"><spanclass="pre">warnings</span></code> library. The
between <aclass="reference external" href="https://docs.python.org/3/library/logging.html#logging.warning" title="(in Python v3.7)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging.warning</span></code></a> and <aclass="reference external" href="https://docs.python.org/3/library/warnings.html#warnings.warn" title="(in Python v3.7)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">warnings.warn</span></code></a> is that
<aclass="reference external" href="https://docs.python.org/3/library/warnings.html#warnings.warn" title="(in Python v3.7)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">warnings.warn</span></code></a> be used for things the user must change to stop
the warning, whereas <aclass="reference external" href="https://docs.python.org/3/library/logging.html#logging.warning" title="(in Python v3.7)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging.warning</span></code></a> can be more persistent.</p>
<p>By default, <aclass="reference external" href="https://docs.python.org/3/library/logging.html#module-logging" title="(in Python v3.7)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging</span></code></a> displays all log messages at levels higher than
<p>Calls to <aclass="reference external" href="https://docs.python.org/3/library/logging.html#logging.info" title="(in Python v3.7)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging.info</span></code></a> are not displayed by default. They are for
information that the user may want to know if the program behaves oddly.
For instance, if an object isn't drawn because its position is <codeclass="docutils literal notranslate"><spanclass="pre">NaN</span></code>,
that can usually be ignored, but a mystified user could set
<codeclass="docutils literal notranslate"><spanclass="pre">logging.basicConfig(level=logging.INFO)</span></code> and get an error message that
says why.</p>
<p><aclass="reference external" href="https://docs.python.org/3/library/logging.html#logging.debug" title="(in Python v3.7)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging.debug</span></code></a> is the least likely to be displayed, and hence can
<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 notranslate"><spanclass="pre">matplotlibrc</span></code> (<aclass="reference internal" href="../tutorials/introductory/customizing.html"><spanclass="doc">Customizing Matplotlib with style sheets and rcParams</span></a>) supports an
external backend via the <codeclass="docutils literal notranslate"><spanclass="pre">module</span></code> directive. If
<codeclass="file docutils literal notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><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>