<h3>Do I really have something to contribute to Matplotlib?<aclass="headerlink" href="#do-i-really-have-something-to-contribute-to-matplotlib" title="Permalink to this heading">#</a></h3>
<p>100% yes. There are so many ways to contribute to our community.</p>
<p>When in doubt, we recommend going together! Get connected with our community of
active contributors, many of whom felt just like you when they started out and
are happy to welcome you and support you as you get to know how we work, and
where things are. Take a look at the next sections to learn more.</p>
</section>
<sectionid="contributor-incubator">
<h3>Contributor incubator<aclass="headerlink" href="#contributor-incubator" title="Permalink to this heading">#</a></h3>
<p>The incubator is our non-public communication channel for new contributors. It
is a private gitter room moderated by core Matplotlib developers where you can
get guidance and support for your first few PRs. It's a place you can ask
questions about anything: how to use git, github, how our PR review process
works, technical questions about the code, what makes for good documentation
or a blog post, how to get involved in community work, or get
"pre-review" on your PR.</p>
<p>To join, please go to our public <aclass="reference external" href="https://gitter.im/matplotlib/matplotlib">gitter</a> community channel, and ask to be
added to '#incubator'. One of our core developers will see your message and will
add you.</p>
</section>
<sectionid="new-contributors-meeting">
<h3>New Contributors meeting<aclass="headerlink" href="#new-contributors-meeting" title="Permalink to this heading">#</a></h3>
<p>Once a month, we host a meeting to discuss topics that interest new
contributors. Anyone can attend, present, or sit in and listen to the call.
Among our attendees are fellow new contributors, as well as maintainers, and
veteran contributors, who are keen to support onboarding of new folks and
share their experience. You can find our community calendar link at the
<aclass="reference external" href="https://scientific-python.org/calendars/">Scientific Python website</a>, and
you can browse previous meeting notes on <aclass="reference external" href="https://github.com/matplotlib/ProjectManagement/tree/master/new_contributor_meeting">github</a>.
We recommend joining the meeting to clarify any doubts, or lingering
questions you might have, and to get to know a few of the people behind the
GitHub handles 😉. You can reach out to @noatamir on <aclass="reference external" href="https://gitter.im/matplotlib/matplotlib">gitter</a> for any clarifications or
suggestions. We <3 feedback!</p>
</section>
<sectionid="issues-for-new-contributors">
<spanid="new-contributors"></span><h3>Issues for new contributors<aclass="headerlink" href="#issues-for-new-contributors" title="Permalink to this heading">#</a></h3>
<p>While any contributions are welcome, we have marked some issues as
particularly suited for new contributors by the label <aclass="reference external" href="https://github.com/matplotlib/matplotlib/labels/good%20first%20issue">good first issue</a>. 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. <codeclass="docutils literal notranslate"><spanclass="pre">Difficulty:</span><spanclass="pre">Easy</span></code> is suited for people with little Python
experience. <codeclass="docutils literal notranslate"><spanclass="pre">Difficulty:</span><spanclass="pre">Medium</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">Difficulty:</span><spanclass="pre">Hard</span></code> require more
programming experience. This could be for a variety of reasons, among them,
though not necessarily all at the same time:</p>
<ulclass="simple">
<li><p>The issue is in areas of the code base which have more interdependencies,
or legacy code.</p></li>
<li><p>It has less clearly defined tasks, which require some independent
exploration, making suggestions, or follow-up discussions to clarify a good
path to resolve the issue.</p></li>
<li><p>It involves Python features such as decorators and context managers, which
have subtleties due to our implementation decisions.</p></li>
</ul>
<p>In general, the Matplotlib project does not assign issues. Issues are
"assigned" or "claimed" by opening a PR; there is no other assignment
mechanism. If you have opened such a PR, please comment on the issue thread to
avoid duplication of work. Please check if there is an existing PR for the
issue you are addressing. If there is, try to work with the author by
submitting reviews of their code or commenting on the PR rather than opening
a new PR; duplicate PRs are subject to being closed. However, if the existing
PR is an outline, unlikely to work, or stalled, and the original author is
unresponsive, feel free to open a new PR referencing the old one.</p>
</section>
</section>
<sectionid="submitting-a-bug-report">
<spanid="id3"></span><h2>Submitting a bug report<aclass="headerlink" href="#submitting-a-bug-report" title="Permalink to this heading">#</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">Issue 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><p>A short, top-level summary of the bug. In most cases, this should be 1-2
sentences.</p></li>
<li><p>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><p>The actual outcome of the code snippet.</p></li>
<li><p>The expected outcome of the code snippet.</p></li>
<li><p>The Matplotlib version, Python version and platform that you are using. You
can grab the version with the following commands:</p>
<p>We have preloaded the issue creation page with a Markdown form that you can
use to organize this information.</p>
<p>Thank you for your help in keeping bug reports complete, targeted and descriptive.</p>
</section>
<sectionid="requesting-a-new-feature">
<spanid="request-a-new-feature"></span><h2>Requesting a new feature<aclass="headerlink" href="#requesting-a-new-feature" title="Permalink to this heading">#</a></h2>
<li><p>Enter the directory and install the local version of Matplotlib.
See <aclass="reference internal" href="development_setup.html#installing-for-devs"><spanclass="std std-ref">Setting up Matplotlib for development</span></a> for instructions</p></li>
<li><p><aclass="reference external" href="https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project">Git-Contributing to a Project</a></p></li>
<li><p><aclass="reference external" href="https://lab.github.com/githubtraining/introduction-to-github">Introduction to GitHub</a></p></li>
<li><p><aclass="reference internal" href="gitwash/development_workflow.html#development-workflow"><spanclass="std std-ref">Development workflow</span></a> for best practices for Matplotlib</p></li>
<li><p><aclass="reference internal" href="gitwash/index.html#using-git"><spanclass="std std-ref">Working with Matplotlib source code</span></a></p></li>
</ul>
</div>
</section>
<sectionid="contributing-pull-requests">
<h3>Contributing pull requests<aclass="headerlink" href="#contributing-pull-requests" title="Permalink to this heading">#</a></h3>
<p>It is recommended to check that your contribution complies with the following
rules before submitting a pull request:</p>
<ul>
<li><p>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><p>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><p>Formatting should follow the recommendations of <aclass="reference external" href="https://www.python.org/dev/peps/pep-0008/">PEP8</a>, as enforced by
<aclass="reference external" href="https://flake8.pycqa.org/">flake8</a>. You can check flake8 compliance from the command line with</p>
<p>or your editor may provide integration with it. Note that Matplotlib
intentionally does not use the <aclass="reference external" href="https://black.readthedocs.io/">black</a> auto-formatter (<aclass="reference external" href="https://github.com/matplotlib/matplotlib/issues/18796">1</a>), in particular due
to its unability to understand the semantics of mathematical expressions
<p>In general, Matplotlib modules should <strong>not</strong> import <aclass="reference internal" href="../api/matplotlib_configuration_api.html#matplotlib.rcParams" title="matplotlib.rcParams"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">rcParams</span></code></a> using <codeclass="docutils literal notranslate"><spanclass="pre">from</span>
<spanclass="pre">matplotlib</span><spanclass="pre">import</span><spanclass="pre">rcParams</span></code>, but rather access it as <codeclass="docutils literal notranslate"><spanclass="pre">mpl.rcParams</span></code>. This
is because some modules are imported very early, before the <aclass="reference internal" href="../api/matplotlib_configuration_api.html#matplotlib.rcParams" title="matplotlib.rcParams"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">rcParams</span></code></a>
singleton is constructed.</p>
</li>
<li><p>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><p>If you change the API in a backward-incompatible way, please document it in
<codeclass="file docutils literal notranslate"><spanclass="pre">doc/api/next_api_changes/behavior</span></code>, by adding a new file with the
naming convention <codeclass="docutils literal notranslate"><spanclass="pre">99999-ABC.rst</span></code> where the pull request number is followed
by the contributor's initials. (see <codeclass="file docutils literal notranslate"><spanclass="pre">doc/api/api_changes.rst</span></code> for more
information)</p></li>
<li><p>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>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>The current state of the Matplotlib code base is not compliant with all
of those guidelines, but we expect that enforcing those constraints on all
new contributions will move the overall code base quality in the right
<spanid="id10"></span><h2>Contributing documentation<aclass="headerlink" href="#contributing-documentation" title="Permalink to this heading">#</a></h2>
<p>You as an end-user of Matplotlib can make a valuable contribution because you
more clearly see the potential for improvement than a core developer. For example, you can:</p>
<ulclass="simple">
<li><p>Fix a typo</p></li>
<li><p>Clarify a docstring</p></li>
<li><p>Write or update an <aclass="reference internal" href="../gallery/index.html#gallery"><spanclass="std std-ref">example plot</span></a></p></li>
<li><p>Write or update a comprehensive <aclass="reference internal" href="../tutorials/index.html#tutorials"><spanclass="std std-ref">tutorial</span></a></p></li>
</ul>
<p>The documentation source files live in the same GitHub repository as the code.
Contributions are proposed and accepted through the pull request process.
For details see <aclass="reference internal" href="#how-to-contribute"><spanclass="std std-ref">How to contribute</span></a>.</p>
<p>If you have trouble getting started, you may instead open an <aclass="reference external" href="https://github.com/matplotlib/matplotlib/issues">issue</a>
<spanid="id12"></span><h2>Coding guidelines<aclass="headerlink" href="#coding-guidelines" title="Permalink to this heading">#</a></h2>
<sectionid="api-changes">
<h3>API changes<aclass="headerlink" href="#api-changes" title="Permalink to this heading">#</a></h3>
<p>API consistency and stability are of great value. Therefore, API changes
(e.g. signature changes, behavior changes, removals) will only be conducted
if the added benefit is worth the user effort for adapting.</p>
<p>API changes in Matplotlib have to be performed following the deprecation process
below, except in very rare circumstances as deemed necessary by the development team.
This ensures that users are notified before the change will take effect and thus
prevents unexpected breaking of code.</p>
<sectionid="rules">
<h4>Rules<aclass="headerlink" href="#rules" title="Permalink to this heading">#</a></h4>
<ulclass="simple">
<li><p>Deprecations are targeted at the next point.release (e.g. 3.x)</p></li>
<li><p>Deprecated API is generally removed two point-releases after introduction
of the deprecation. Longer deprecations can be imposed by core developers on
a case-by-case basis to give more time for the transition</p></li>
<li><p>The old API must remain fully functional during the deprecation period</p></li>
<li><p>If alternatives to the deprecated API exist, they should be available
during the deprecation period</p></li>
<li><p>If in doubt, decisions about API changes are finally made by the
API consistency lead developer</p></li>
</ul>
</section>
<sectionid="introducing">
<h4>Introducing<aclass="headerlink" href="#introducing" title="Permalink to this heading">#</a></h4>
<olclass="arabic">
<li><p>Announce the deprecation in a new file
<codeclass="file docutils literal notranslate"><spanclass="pre">doc/api/next_api_changes/deprecations/99999-ABC.rst</span></code> where <codeclass="docutils literal notranslate"><spanclass="pre">99999</span></code>
is the pull request number and <codeclass="docutils literal notranslate"><spanclass="pre">ABC</span></code> are the contributor's initials.</p></li>
<li><p>If possible, issue a <aclass="reference internal" href="../api/matplotlib_configuration_api.html#matplotlib.MatplotlibDeprecationWarning" title="matplotlib.MatplotlibDeprecationWarning"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">MatplotlibDeprecationWarning</span></code></a> when the
deprecated API is used. There are a number of helper tools for this:</p>
<ulclass="simple">
<li><p>Use <codeclass="docutils literal notranslate"><spanclass="pre">_api.warn_deprecated()</span></code> for general deprecation warnings</p></li>
<li><p>Use the decorator <codeclass="docutils literal notranslate"><spanclass="pre">@_api.deprecated</span></code> to deprecate classes, functions,
methods, or properties</p></li>
<li><p>To warn on changes of the function signature, use the decorators
<codeclass="docutils literal notranslate"><spanclass="pre">@_api.delete_parameter</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">@_api.rename_parameter</span></code>, and
<p>All these helpers take a first parameter <em>since</em>, which should be set to
the next point release, e.g. "3.x".</p>
<p>You can use standard rst cross references in <em>alternative</em>.</p>
</li>
</ol>
</section>
<sectionid="expiring">
<h4>Expiring<aclass="headerlink" href="#expiring" title="Permalink to this heading">#</a></h4>
<olclass="arabic simple">
<li><p>Announce the API changes in a new file
<codeclass="file docutils literal notranslate"><spanclass="pre">doc/api/next_api_changes/[kind]/99999-ABC.rst</span></code> where <codeclass="docutils literal notranslate"><spanclass="pre">99999</span></code>
is the pull request number and <codeclass="docutils literal notranslate"><spanclass="pre">ABC</span></code> are the contributor's initials, and
<codeclass="docutils literal notranslate"><spanclass="pre">[kind]</span></code> is one of the folders <codeclass="file docutils literal notranslate"><spanclass="pre">behavior</span></code>, <codeclass="file docutils literal notranslate"><spanclass="pre">development</span></code>,
<codeclass="file docutils literal notranslate"><spanclass="pre">removals</span></code>. See <codeclass="file docutils literal notranslate"><spanclass="pre">doc/api/next_api_changes/README.rst</span></code> for more
information. For the content, you can usually copy the deprecation notice
and adapt it slightly.</p></li>
<li><p>Change the code functionality and remove any related deprecation warnings.</p></li>
</ol>
</section>
</section>
<sectionid="adding-new-api">
<h3>Adding new API<aclass="headerlink" href="#adding-new-api" title="Permalink to this heading">#</a></h3>
<p>Every new function, parameter and attribute that is not explicitly marked as
private (i.e., starts with an underscore) becomes part of Matplotlib's public
API. As discussed above, changing the existing API is cumbersome. Therefore,
take particular care when adding new API:</p>
<ulclass="simple">
<li><p>Mark helper functions and internal attributes as private by prefixing them
with an underscore.</p></li>
<li><p>Carefully think about good names for your functions and variables.</p></li>
<li><p>Try to adopt patterns and naming conventions from existing parts of the
Matplotlib API.</p></li>
<li><p>Consider making as many arguments keyword-only as possible. See also
<aclass="reference external" href="https://emptysqua.re/blog/api-evolution-the-right-way/#adding-parameters">API Evolution the Right Way -- Add Parameters Compatibly</a>.</p>
</li>
</ul>
</section>
<sectionid="new-modules-and-files-installation">
<h3>New modules and files: installation<aclass="headerlink" href="#new-modules-and-files-installation" title="Permalink to this heading">#</a></h3>
<ulclass="simple">
<li><p>If you have added new files or directories, or reorganized existing
ones, make sure the new files are included in the match patterns in
in <em>package_data</em> in <codeclass="file docutils literal notranslate"><spanclass="pre">setupext.py</span></code>.</p></li>