You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP12.html">MEP12: Improve Gallery and Examples</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP13.html">MEP13: Use properties for Artists</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP14.html">MEP14: Text handling</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP15.html">MEP15: Fix axis autoscaling when limits are specified for one axis only</a></li>
<spanid="contributing"></span><h1>Contribute<aclass="headerlink" href="#contribute" title="Link to this heading">#</a></h1>
<p>You've discovered a bug or something else you want to change
in Matplotlib — excellent!</p>
<p>You've worked out a way to fix it — even better!</p>
<p>You want to tell us about it — best of all!</p>
<p>This project is a community effort, and everyone is welcome to contribute. Everyone
within the community is expected to abide by our <aclass="reference external" href="https://github.com/matplotlib/matplotlib/blob/main/CODE_OF_CONDUCT.md">code of conduct</a>.</p>
<p>Below, you can find a number of ways to contribute, and how to connect with the
Matplotlib community.</p>
<sectionid="get-started">
<spanid="start-contributing"></span><h2>Get started<aclass="headerlink" href="#get-started" title="Link to this heading">#</a></h2>
<p>There is no pre-defined pathway for new contributors -- we recommend looking at
existing issue and pull request discussions, and following the conversations
during pull request reviews to get context. Or you can deep-dive into a subset
of the code-base to understand what is going on.</p>
<p>There are a few typical new contributor profiles:</p>
<ul>
<li><p><strong>You are a Matplotlib user, and you see a bug, a potential improvement, or
something that annoys you, and you can fix it.</strong></p>
<p>You can search our issue tracker for an existing issue that describes your problem or
open a new issue to inform us of the problem you observed and discuss the best approach
to fix it. If your contributions would not be captured on GitHub (social media,
communication, educational content), you can also reach out to us on <aclass="reference external" href="https://gitter.im/matplotlib/matplotlib">gitter</a>,
<aclass="reference external" href="https://discourse.matplotlib.org/">Discourse</a> or attend any of our <aclass="reference external" href="https://scientific-python.org/calendars">community
meetings</a>.</p>
</li>
<li><p><strong>You are not a regular Matplotlib user but a domain expert: you know about
visualization, 3D plotting, design, technical writing, statistics, or some
other field where Matplotlib could be improved.</strong></p>
<p>Awesome -- you have a focus on a specific application and domain and can
start there. In this case, maintainers can help you figure out the best
implementation; open an issue or pull request with a starting point, and we'll
be happy to discuss technical approaches.</p>
<p>If you prefer, you can use the <aclass="reference external" href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#converting-a-pull-request-to-a-draft">GitHub functionality for "draft" pull requests</a>
and request early feedback on whatever you are working on, but you should be
aware that maintainers may not review your contribution unless it has the
"Ready to review" state on GitHub.</p>
</li>
<li><p><strong>You are new to Matplotlib, both as a user and contributor, and want to start
contributing but have yet to develop a particular interest.</strong></p>
<p>Having some previous experience or relationship with the library can be very
helpful when making open-source contributions. It helps you understand why
things are the way they are and how they <em>should</em> be. Having first-hand
experience and context is valuable both for what you can bring to the
conversation (and given the breadth of Matplotlib's usage, there is a good
chance it is a unique context in any given conversation) and make it easier to
understand where other people are coming from.</p>
<p>Understanding the entire codebase is a long-term project, and nobody expects
you to do this right away. If you are determined to get started with
Matplotlib and want to learn, going through the basic functionality,
choosing something to focus on (3d, testing, documentation, animations, etc.)
and gaining context on this area by reading the issues and pull requests
touching these subjects is a reasonable approach.</p>
</li>
</ul>
</section>
<sectionid="get-connected">
<spanid="id1"></span><h2>Get connected<aclass="headerlink" href="#get-connected" title="Link to this heading">#</a></h2>
<h3>Do I really have something to contribute to Matplotlib?<aclass="headerlink" href="#do-i-really-have-something-to-contribute-to-matplotlib" title="Link 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="Link to this heading">#</a></h3>
<p>The incubator is our non-public communication channel for new contributors. It
is a private <aclass="reference external" href="https://gitter.im/matplotlib/matplotlib">gitter</a> (chat) room moderated by core Matplotlib developers where
you can get guidance and support for your first few PRs. It's a place where 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 a
"pre-review" on your PR.</p>
<p>To join, please go to our public <aclass="reference external" href="https://gitter.im/matplotlib/community">community</a> channel, and ask to be added to
<codeclass="docutils literal notranslate"><spanclass="pre">#incubator</span></code>. 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="Link 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 us on <aclass="reference external" href="https://gitter.im/matplotlib/matplotlib">gitter</a> for any clarifications or
suggestions. We ❤ feedback!</p>
</section>
<sectionid="good-first-issues">
<spanid="new-contributors"></span><h3>Good first issues<aclass="headerlink" href="#good-first-issues" title="Link 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>
</section>
<sectionid="work-on-an-issue">
<spanid="managing-issues-prs"></span><h3>Work on an issue<aclass="headerlink" href="#work-on-an-issue" title="Link to this heading">#</a></h3>
<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="submit-a-bug-report">
<spanid="submitting-a-bug-report"></span><h2>Submit a bug report<aclass="headerlink" href="#submit-a-bug-report" title="Link 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>See <aclass="reference internal" href="development_setup.html#installing-for-devs"><spanclass="std std-ref">Setting up Matplotlib for development</span></a> for detailed instructions.</p>
<p>and start making changes. Never work in the <codeclass="docutils literal notranslate"><spanclass="pre">main</span></code> branch!</p>
</li>
<li><p>Work on this task using Git to do the version control. Codespaces persist for
some time (check the <aclass="reference external" href="https://docs.github.com/codespaces/getting-started/the-codespace-lifecycle">documentation for details</a>)
and can be managed on <aclass="github reference external" href="https://github.com/codespaces">codespaces</a>. When you're done editing
<h4>Open a pull request on Matplotlib<aclass="headerlink" href="#open-a-pull-request-on-matplotlib" title="Link to this heading">#</a></h4>
<p>Finally, go to the web page of <em>your fork</em> of the Matplotlib repo, and click
<strong>Compare & pull request</strong> to send your changes to the maintainers for review.
The base repository is <codeclass="docutils literal notranslate"><spanclass="pre">matplotlib/matplotlib</span></code> and the base branch is
generally <codeclass="docutils literal notranslate"><spanclass="pre">main</span></code>. For more guidance, see GitHub's <aclass="reference external" href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork">pull request tutorial</a>.</p>
<p>For more detailed instructions on how to set up Matplotlib for development and
best practices for contribution, see <aclass="reference internal" href="development_setup.html#installing-for-devs"><spanclass="std std-ref">Setting up Matplotlib for development</span></a>.</p>
</section>
<sectionid="github-codespaces-workflows">
<h4>GitHub Codespaces workflows<aclass="headerlink" href="#github-codespaces-workflows" title="Link to this heading">#</a></h4>
<ul>
<li><p>If you need to open a GUI window with Matplotlib output on Codespaces, our
configuration includes a <aclass="reference external" href="https://github.com/devcontainers/features/tree/main/src/desktop-lite">light-weight Fluxbox-based desktop</a>.
You can use it by connecting to this desktop via your web browser. To do this:</p>
<olclass="arabic simple">
<li><p>Press <codeclass="docutils literal notranslate"><spanclass="pre">F1</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">Ctrl/Cmd+Shift+P</span></code> and select
<codeclass="docutils literal notranslate"><spanclass="pre">Ports:</span><spanclass="pre">Focus</span><spanclass="pre">on</span><spanclass="pre">Ports</span><spanclass="pre">View</span></code> in the VSCode session to bring it into
focus. Open the ports view in your tool, select the <codeclass="docutils literal notranslate"><spanclass="pre">noVNC</span></code> port, and
click the Globe icon.</p></li>
<li><p>In the browser that appears, click the Connect button and enter the desktop
password (<codeclass="docutils literal notranslate"><spanclass="pre">vscode</span></code> by default).</p></li>
</ol>
<p>Check the <aclass="reference external" href="https://github.com/devcontainers/features/tree/main/src/desktop-lite#connecting-to-the-desktop">GitHub instructions</a>
for more details on connecting to the desktop.</p>
</li>
<li><p>If you also built the documentation pages, you can view them using Codespaces.
Use the "Extensions" icon in the activity bar to install the "Live Server"
extension. Locate the <codeclass="docutils literal notranslate"><spanclass="pre">doc/build/html</span></code> folder in the Explorer, right click
the file you want to open and select "Open with Live Server."</p></li>
</ul>
</section>
</section>
</section>
<sectionid="contribute-documentation">
<spanid="contributing-documentation"></span><h2>Contribute documentation<aclass="headerlink" href="#contribute-documentation" title="Link 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="id6"></span><h2>Coding guidelines<aclass="headerlink" href="#coding-guidelines" title="Link to this heading">#</a></h2>
<p>While the current state of the Matplotlib code base is not compliant with all
of these guidelines, our goal in enforcing these constraints on new
contributions is that it improves the readability and consistency of the code base
going forward.</p>
<sectionid="pep8-as-enforced-by-flake8">
<h3>PEP8, as enforced by flake8<aclass="headerlink" href="#pep8-as-enforced-by-flake8" title="Link to this heading">#</a></h3>
<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>.
Matplotlib modifies PEP8 to extend the maximum line length to 88
characters. 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 inability
to understand the semantics of mathematical expressions (<aclass="reference external" href="https://github.com/psf/black/issues/148">2</a>, <aclass="reference external" href="https://github.com/psf/black/issues/1984">3</a>).</p>
</section>
<sectionid="package-imports">
<h3>Package imports<aclass="headerlink" href="#package-imports" title="Link to this heading">#</a></h3>
<p>Import the following modules using the standard scipy conventions:</p>
<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>
</section>
<sectionid="variable-names">
<h3>Variable names<aclass="headerlink" href="#variable-names" title="Link to this heading">#</a></h3>
<p>When feasible, please use our internal variable naming convention for objects
of a given class and objects of any child class:</p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">trans_<source></span></code> when target is screen</p>
</td>
</tr>
<trclass="row-odd"></tr>
</tbody>
</table>
<p>Generally, denote more than one instance of the same class by adding suffixes to
the variable names. If a format isn't specified in the table, use numbers or
letters as appropriate.</p>
</section>
<sectionid="type-hints">
<spanid="id10"></span><h3>Type hints<aclass="headerlink" href="#type-hints" title="Link to this heading">#</a></h3>
<p>If you add new public API or change public API, update or add the
corresponding <aclass="reference external" href="https://mypy.readthedocs.io/en/latest/">mypy</a> type hints.
We generally use <aclass="reference external" href="https://typing.readthedocs.io/en/latest/source/stubs.html#type-stubs">stub files</a>
(<codeclass="docutils literal notranslate"><spanclass="pre">*.pyi</span></code>) to store the type information; for example <codeclass="docutils literal notranslate"><spanclass="pre">colors.pyi</span></code> contains
the type information for <codeclass="docutils literal notranslate"><spanclass="pre">colors.py</span></code>. A notable exception is <codeclass="docutils literal notranslate"><spanclass="pre">pyplot.py</span></code>,
which is type hinted inline.</p>
<p>Type hints are checked by the mypy <aclass="reference internal" href="development_setup.html#pre-commit-hooks"><spanclass="std std-ref">pre-commit hook</span></a>
and can often be verified using <codeclass="docutils literal notranslate"><spanclass="pre">tools\stubtest.py</span></code> and occasionally may
require the use of <codeclass="docutils literal notranslate"><spanclass="pre">tools\check_typehints.py</span></code>.</p>
</section>
<sectionid="api-changes-and-new-features">
<spanid="new-changed-api"></span><h3>API changes and new features<aclass="headerlink" href="#api-changes-and-new-features" title="Link 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 effort of adapting existing code.</p>
<p>Because we are a visualization library, our primary output is the final
visualization the user sees; therefore, the appearance of the figure is part of
the API and any changes, either semantic or <aclass="reference internal" href="color_changes.html#color-changes"><spanclass="std std-ref">esthetic</span></a>,
<spanid="api-whats-new"></span><h4>Announce changes, deprecations, and new features<aclass="headerlink" href="#announce-changes-deprecations-and-new-features" title="Link to this heading">#</a></h4>
<p>When adding or changing the API in a backward in-compatible way, please add the
appropriate <aclass="reference internal" href="#versioning-directives"><spanclass="std std-ref">versioning directive</span></a> and document it
for the release notes and add the entry to the appropriate folder:</p>
<p>For both change notes and what's new, please avoid using references in section
titles, as it causes links to be confusing in the table of contents. Instead,
ensure that a reference is included in the descriptive text.</p>
<sectionid="api-change-notes">
<h5>API Change Notes<aclass="headerlink" href="#api-change-notes" title="Link to this heading">#</a></h5>
<p>API change notes for future releases are collected in
<codeclass="file docutils literal notranslate"><spanclass="pre">next_api_changes</span></code>. They are divided into four subdirectories:</p>
<ulclass="simple">
<li><p><strong>Deprecations</strong>: Announcements of future changes. Typically, these will
raise a deprecation warning and users of this API should change their code
to stay compatible with future releases of Matplotlib. If possible, state
what should be used instead.</p></li>
<li><p><strong>Removals</strong>: Parts of the API that got removed. If possible, state what
should be used instead.</p></li>
<li><p><strong>Behaviour changes</strong>: API that stays valid but will yield a different
result.</p></li>
<li><p><strong>Development changes</strong>: Changes to the build process, dependencies, etc.</p></li>
</ul>
<p>Please place new entries in these directories with a new file named
<codeclass="docutils literal notranslate"><spanclass="pre">99999-ABC.rst</span></code>, where <codeclass="docutils literal notranslate"><spanclass="pre">99999</span></code> would be the PR number, and <codeclass="docutils literal notranslate"><spanclass="pre">ABC</span></code> the
author's initials. Typically, each change will get its own file, but you may
also amend existing files when suitable. The overall goal is a comprehensible