<divid="unreleased-message"> You are reading an old version of the documentation (v3.0.2). For the latest version see <ahref="https://matplotlib.org/stable/devel/release_guide.html">https://matplotlib.org/stable/devel/release_guide.html</a></div>
<p>Review and commit changes. Some issue/PR titles may not be valid rst (the most common issue is
<codeclass="docutils literal notranslate"><spanclass="pre">*</span></code> which is interpreted as unclosed markup).</p>
</div>
<divclass="section" id="check-docs">
<spanid="release-chkdocs"></span><h3>Check Docs<aclass="headerlink" href="#check-docs" title="Permalink to this headline">¶</a></h3>
<p>Before tagging, update the what's new listing in <codeclass="file docutils literal notranslate"><spanclass="pre">doc/users/whats_new.rst</span></code>
by merging all files in <codeclass="file docutils literal notranslate"><spanclass="pre">doc/users/next_whats_new/</span></code> coherently. Also,
temporarily comment out the include and toctree glob; re-instate these after a
release. 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>-n<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
<spanid="release-doi"></span><h3>Release Management / DOI<aclass="headerlink" href="#release-management-doi" title="Permalink to this headline">¶</a></h3>
<p>Via the GitHub UI (chase down link), 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/_templates/citing.html</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 master of <aclass="reference external" href="https://github.com/MacPython/matplotlib-wheels">the build
project</a>.</p>
<p>Update the <codeclass="docutils literal notranslate"><spanclass="pre">master</span></code> branch (for pre-releases the <codeclass="docutils literal notranslate"><spanclass="pre">devel</span></code> branch)
of the <aclass="reference external" href="https://github.com/conda-forge/matplotlib-feedstock">conda-forge feedstock</a> via pull request.</p>
<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, generate the tarball</p>
<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="http://matplotlib.org/devdocs">matplotlib.org/devdocs</a>.</p>
<p>Assuming you have this repository checked out in the same directory as