<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="api-changes"></span><h1>API guidelines<aclass="headerlink" href="#api-guidelines" title="Link to this heading">#</a></h1>
<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 aesthetic, are backwards-incompatible
API changes.</p>
<sectionid="add-new-api-and-features">
<h2>Add new API and features<aclass="headerlink" href="#add-new-api-and-features" title="Link to this heading">#</a></h2>
<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>
<h2>Add or change colormaps, color sequences, and styles<aclass="headerlink" href="#add-or-change-colormaps-color-sequences-and-styles" title="Link to this heading">#</a></h2>
<p>Visual changes are considered an API break. Therefore, we generally do not modify
existing colormaps, color sequences, or styles.</p>
<p>We put a high bar on adding new colormaps and styles to prevent excessively growing
them. While the decision is case-by-case, evaluation criteria include:</p>
<ulclass="simple">
<li><p>novelty: Does it support a new use case? e.g. slight variations of existing maps,
sequences and styles are likely not accepted.</p></li>
<li><p>usability and accessibility: Are colors of sequences sufficiently distinct? Has
colorblindness been considered?</p></li>
<li><p>evidence of wide spread usage: for example academic papers, industry blogs and
whitepapers, or inclusion in other visualization libraries or domain specific tools</p></li>
<li><p>open license: colormaps, sequences, and styles must have a BSD compatible license
(see <aclass="reference internal" href="license.html#license-discussion"><spanclass="std std-ref">Licenses for contributed code</span></a>)</p></li>
</ul>
</section>
<sectionid="deprecate-api">
<spanid="deprecation-guidelines"></span><h2>Deprecate API<aclass="headerlink" href="#deprecate-api" title="Link to this heading">#</a></h2>
<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. Generally API deprecation happens in two stages:</p>
<ulclass="simple">
<li><p><strong>introduce:</strong> warn users that the API <em>will</em> change</p></li>
<li><p><strong>expire:</strong> API <em>is</em> changed as described in the introduction period</p></li>
</ul>
<p>This ensures that users are notified before the change will take effect and thus
prevents unexpected breaking of code.</p>
<sectionid="rules">
<h3>Rules<aclass="headerlink" href="#rules" title="Link to this heading">#</a></h3>
<ulclass="simple">
<li><p>Deprecations are targeted at the next <aclass="reference internal" href="pr_guide.html#pr-milestones"><spanclass="std std-ref">meso release</span></a> (e.g. 3.x)</p></li>
<li><p>Deprecated API is generally removed (expired) 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
<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>Use <codeclass="docutils literal notranslate"><spanclass="pre">@_api.deprecate_privatize_attribute</span></code> to annotate deprecation of
attributes while keeping the internal private version.</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>
<li><p>Make appropriate changes to the type hints in the associated <codeclass="docutils literal notranslate"><spanclass="pre">.pyi</span></code> file.
The general guideline is to match runtime reported behavior.</p>
<ulclass="simple">
<li><p>Items marked with <codeclass="docutils literal notranslate"><spanclass="pre">@_api.deprecated</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">@_api.deprecate_privatize_attribute</span></code>
are generally kept during the expiry period, and thus no changes are needed on
introduction.</p></li>
<li><p>Items decorated with <codeclass="docutils literal notranslate"><spanclass="pre">@_api.rename_parameter</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">@_api.make_keyword_only</span></code>
report the <em>new</em> (post deprecation) signature at runtime, and thus <em>should</em> be
updated on introduction.</p></li>
<li><p>Items decorated with <codeclass="docutils literal notranslate"><spanclass="pre">@_api.delete_parameter</span></code> should include a default value hint
for the deleted parameter, even if it did not previously have one (e.g.
<spanid="id2"></span><h3>Expire deprecation<aclass="headerlink" href="#expire-deprecation" title="Link to this heading">#</a></h3>
<olclass="arabic simple">
<li><p>Create <aclass="reference internal" href="#api-whats-new"><spanclass="std std-ref">deprecation announcement</span></a>. 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>
<li><p>Make appropriate changes to the type hints in the associated <codeclass="docutils literal notranslate"><spanclass="pre">.pyi</span></code> file.</p>
<ulclass="simple">
<li><p>Items marked with <codeclass="docutils literal notranslate"><spanclass="pre">@_api.deprecated</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">@_api.deprecate_privatize_attribute</span></code>
are to be removed on expiry.</p></li>
<li><p>Items decorated with <codeclass="docutils literal notranslate"><spanclass="pre">@_api.rename_parameter</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">@_api.make_keyword_only</span></code>
will have been updated at introduction, and require no change now.</p></li>
<li><p>Items decorated with <codeclass="docutils literal notranslate"><spanclass="pre">@_api.delete_parameter</span></code> will need to be updated to the
final signature, in the same way as the <codeclass="docutils literal notranslate"><spanclass="pre">.py</span></code> file signature is updated.</p></li>
<li><p>Any entries in <codeclass="file docutils literal notranslate"><spanclass="pre">ci/mypy-stubtest-allowlist.txt</span></code> which indicate a deprecation
version should be double checked. In most cases this is not needed, though some
items were never type hinted in the first place and were added to this file
instead. For removed items that were not in the stub file, only deleting from the
allowlist is required.</p></li>
</ul>
</li>
</ol>
</section>
</section>
<sectionid="announce-new-and-deprecated-api">
<spanid="api-whats-new"></span><h2>Announce new and deprecated API<aclass="headerlink" href="#announce-new-and-deprecated-api" title="Link to this heading">#</a></h2>
<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 classes and functions, the directive should be placed before the
<em>Parameters</em> section. For parameters, the directive should be placed at the
end of the parameter description. The micro release version is omitted and
the directive should not be added to entire modules.</p>
</section>
<sectionid="release-notes">
<h3>Release notes<aclass="headerlink" href="#release-notes" title="Link to this heading">#</a></h3>
<p>For both change notes and what's new, please avoid using cross-references in section
titles as it causes links to be confusing in the table of contents. Instead, ensure that
a cross-reference is included in the descriptive text.</p>
<sectionid="api-change-notes">
<spanid="id4"></span><h4>API change notes<aclass="headerlink" href="#api-change-notes" title="Link to this heading">#</a></h4>
<p>API change notes for future releases are collected in <codeclass="file docutils literal notranslate"><spanclass="pre">doc/api/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
<liclass="toc-h2 nav-item toc-entry"><aclass="reference internal nav-link" href="#add-new-api-and-features">Add new API and features</a></li>
<liclass="toc-h2 nav-item toc-entry"><aclass="reference internal nav-link" href="#add-or-change-colormaps-color-sequences-and-styles">Add or change colormaps, color sequences, and styles</a></li>