<divid="unreleased-message"> You are reading an old version of the documentation (v3.2.0). For the latest version see <ahref="https://matplotlib.org/stable/devel/release_guide.html">https://matplotlib.org/stable/devel/release_guide.html</a></div>
<pclass="first admonition-title">This document is only relevant for Matplotlib release managers.</p>
<pclass="last">A guide for developers who are doing a Matplotlib release.</p>
</div>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">This assumes that a read-only remote for the canonical repository is
<codeclass="docutils literal notranslate"><spanclass="pre">remote</span></code> and a read/write remote is <codeclass="docutils literal notranslate"><spanclass="pre">DANGER</span></code></p>
</div>
<divclass="section" id="all-releases">
<h2>All Releases<aclass="headerlink" href="#all-releases" title="Permalink to this headline">¶</a></h2>
<divclass="section" id="testing">
<spanid="release-testing"></span><h3>Testing<aclass="headerlink" href="#testing" title="Permalink to this headline">¶</a></h3>
<p>We use <aclass="reference external" href="https://travis-ci.org/matplotlib/matplotlib">travis-ci</a> for
continuous integration. When preparing for a release, the final
tagged commit should be tested locally before it is uploaded:</p>
<spanid="release-ghstats"></span><h3>GitHub Stats<aclass="headerlink" href="#github-stats" title="Permalink to this headline">¶</a></h3>
<p>We automatically extract GitHub issue, PRs, and authors from GitHub via the API.
copy the current <codeclass="file docutils literal notranslate"><spanclass="pre">github_stats.rst</span></code> to <codeclass="file docutils literal notranslate"><spanclass="pre">github_stats_X.Y.Z.rst</span></code>.</p>
<spanid="release-chkdocs"></span><h3>Update and Validate the Docs<aclass="headerlink" href="#update-and-validate-the-docs" title="Permalink to this headline">¶</a></h3>
<p>Merge the most recent 'doc' branch (<codeclass="docutils literal notranslate"><spanclass="pre">v3.0.2-doc</span></code>) into the branch you
are going to tag on and delete the doc branch on GitHub.</p>
<p>Before tagging, update the "what's new" and "API changes" listings.</p>
<p>for the "what's new"</p>
<blockquote>
<div><olclass="arabic simple">
<li>copy the current content to a file in <codeclass="file docutils literal notranslate"><spanclass="pre">doc/users/prev_whats_new</span></code></li>
<li>merge all of the files in <codeclass="file docutils literal notranslate"><spanclass="pre">doc/users/next_whats_new/</span></code> into
<codeclass="file docutils literal notranslate"><spanclass="pre">doc/users/whats_new.rst</span></code> and delete the individual files</li>
<li>comment out the next whats new glob at the top</li>
</ol>
</div></blockquote>
<p>Similarly for the "API changes"</p>
<blockquote>
<div><olclass="arabic simple">
<li>copy the current api changes to a file is <codeclass="file docutils literal notranslate"><spanclass="pre">doc/api/prev_api_changes</span></code></li>
<li>merge all of the files in <codeclass="file docutils literal notranslate"><spanclass="pre">doc/api/next_api_changes/</span></code> into
<li>comment out the next API changes at the top.</li>
</ol>
</div></blockquote>
<p>In both cases step 3 will have to be un-done right after the release.</p>
<p>Finally, make sure that the docs build cleanly</p>
<divclass="highlight-bash notranslate"><divclass="highlight"><pre><span></span>make -Cdoc <spanclass="nv">O</span><spanclass="o">=</span>-j<spanclass="k">$(</span>nproc<spanclass="k">)</span> html latexpdf
</pre></div>
</div>
<p>After the docs are built, check that all of the links, internal and external, are still
valid. We use <codeclass="docutils literal notranslate"><spanclass="pre">linkchecker</span></code> for this, which has not been ported to python3 yet. You will
need to create a python2 environment with <codeclass="docutils literal notranslate"><spanclass="pre">requests==2.9.0</span></code> and linkchecker</p>
<spanid="release-tag"></span><h3>Create release commit and tag<aclass="headerlink" href="#create-release-commit-and-tag" title="Permalink to this headline">¶</a></h3>
<p>To create the tag, first create an empty commit with a very terse set of the release notes
<p>and then create a signed, annotated tag with the same text in the body
message</p>
<divclass="highlight-bash notranslate"><divclass="highlight"><pre><span></span>git tag -a -s v2.0.0
</pre></div>
</div>
<p>which will prompt you for your gpg key password and an annotation.
For pre releases it is important to follow <spanclass="target" id="index-0"></span><aclass="pep reference external" href="https://www.python.org/dev/peps/pep-0440"><strong>PEP 440</strong></a> so that the
build artifacts will sort correctly in pypi. Finally, push the tag to GitHub</p>
<tr><tdclass="label"><aclass="fn-backref" href="#id2">[1]</a></td><td><pclass="first">The tarball that is provided by GitHub is produced using <aclass="reference external" href="https://git-scm.com/docs/git-archive">git
<codeclass="file docutils literal notranslate"><spanclass="pre">lib/matplotlib/_version.py</span></code> to have <codeclass="docutils literal notranslate"><spanclass="pre">git</span></code> insert a
list of references to exported commit (see
<codeclass="file docutils literal notranslate"><spanclass="pre">.gitattributes</span></code> for the configuration). This string is
then used by <codeclass="docutils literal notranslate"><spanclass="pre">versioneer</span></code> to produce the correct version,
based on the git tag, when users install from the tarball.
However, if there is a branch pointed at the tagged commit,
then the branch name will also be included in the tarball.
When the branch eventually moves, anyone how checked the hash
of the tarball before the branch moved will have an incorrect
<p>On this branch un-comment the globs from <aclass="reference internal" href="#release-chkdocs"><spanclass="std std-ref">Update and Validate the Docs</span></a>. And then</p>
<spanid="release-doi"></span><h3>Release Management / DOI<aclass="headerlink" href="#release-management-doi" title="Permalink to this headline">¶</a></h3>
<p>Via the <aclass="reference external" href="https://github.com/matplotlib/matplotlib/releases">GitHub UI</a>, turn the newly
pushed tag into a release. If this is a pre-release remember to mark
it as such.</p>
<p>For final releases also get a DOI from <aclass="reference external" href="https://zenodo.org/">zenodo</a> and edit <codeclass="file docutils literal notranslate"><spanclass="pre">doc/citing.rst</span></code> with DOI link
and commit to the VER-doc branch and push to GitHub</p>
<spanid="release-bld-bin"></span><h3>Building binaries<aclass="headerlink" href="#building-binaries" title="Permalink to this headline">¶</a></h3>
<p>We distribute mac, windows, and many linux wheels as well as a source
tarball via pypi. Before uploading anything, contact the various
builders. Mac and manylinux wheels are built on travis . You need to
edit the <codeclass="file docutils literal notranslate"><spanclass="pre">.travis.yml</span></code> file and push to the correct branch of
<aclass="reference external" href="https://github.com/MacPython/matplotlib-wheels">the build project</a>. For new minor
versions create a new branch, for bug-fixes continue to use the current
release branch.</p>
<p>The auto-tick bot should open a pull request into the <aclass="reference external" href="https://github.com/conda-forge/matplotlib-feedstock">conda-forge
feedstock</a>.
Review and merge (if you have the power to).</p>
<divclass="admonition warning">
<pclass="first admonition-title">Warning</p>
<pclass="last">Because this is automated, it is extremely important to bump all branches
away from the tag as discussed in <aclass="reference internal" href="#release-tag"><spanclass="std std-ref">Create release commit and tag</span></a>.</p>
</div>
<p>If this is a final release the following downstream packagers should be contacted:</p>
<ulclass="simple">
<li>Debian</li>
<li>Fedora</li>
<li>Arch</li>
<li>Gentoo</li>
<li>Macports</li>
<li>Homebrew</li>
<li>Christoph Gohlke</li>
<li>Continuum</li>
<li>Enthought</li>
</ul>
<p>This can be done ahead of collecting all of the binaries and uploading to pypi.</p>
<spanid="release-upload-bin"></span><h3>make distribution and upload to pypi / SF<aclass="headerlink" href="#make-distribution-and-upload-to-pypi-sf" title="Permalink to this headline">¶</a></h3>
<p>Once you have collected all of the wheels (expect this to take about a
<spanid="release-docs"></span><h3>Build and Deploy Documentation<aclass="headerlink" href="#build-and-deploy-documentation" title="Permalink to this headline">¶</a></h3>
<p>To build the documentation you must have the tagged version installed, but
build the docs from the <codeclass="docutils literal notranslate"><spanclass="pre">ver-doc</span></code> branch. An easy way to arrange this is:</p>
make <spanclass="nv">O</span><spanclass="o">=</span>-n<spanclass="k">$(</span>nproc<spanclass="k">)</span> html latexpdf
</pre></div>
</div>
<p>which will build both the html and pdf version of the documentation.</p>
<p>The built documentation exists in the <aclass="reference external" href="https://github.com/matplotlib/matplotlib.github.com/">matplotlib.github.com</a> repository.
Pushing changes to master automatically updates the website.</p>
<p>The documentation is organized by version. At the root of the tree is
always the documentation for the latest stable release. Under that,
there are directories containing the documentation for older versions.
The documentation for current master are built on travis and push to
the <aclass="reference external" href="https://github.com/matplotlib/devdocs/">devdocs</a> repository.
These are available at <aclass="reference external" href="https://matplotlib.org/devdocs">matplotlib.org/devdocs</a>.</p>
<p>Assuming you have this repository checked out in the same directory as