<h1>Adding API change notes<aclass="headerlink" href="#adding-api-change-notes" title="Permalink to this headline">¶</a></h1>
<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
documentation of the changes.</p>
<p>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. A typical entry could look like this:</p>