<divid="unreleased-message"> You are reading an old version of the documentation (v1.4.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>
<spanid="release-guide"></span><h1>Doing a matplotlib release<aclass="headerlink" href="#doing-a-matplotlib-release" title="Permalink to this headline">¶</a></h1>
<p>A guide for developers who are doing a matplotlib release.</p>
<ulclass="simple">
<li>Edit <codeclass="file docutils literal"><spanclass="pre">__init__.py</span></code> and bump the version number</li>
</ul>
<divclass="section" id="testing">
<spanid="release-testing"></span><h2>Testing<aclass="headerlink" href="#testing" title="Permalink to this headline">¶</a></h2>
<ulclass="simple">
<li>Run all of the regression tests by running the <codeclass="xref py py-obj docutils literal"><spanclass="pre">tests.py</span></code> script at
the root of the source tree.</li>
<li>Run <codeclass="file docutils literal"><spanclass="pre">unit/memleak_hawaii3.py</span></code> and make sure there are no
memory leaks</li>
<li>try some GUI examples, eg <codeclass="file docutils literal"><spanclass="pre">simple_plot.py</span></code> with GTKAgg, TkAgg, etc...</li>
<li>remove font cache and tex cache from <codeclass="file docutils literal"><spanclass="pre">.matplotlib</span></code> and test
with and without cache on some example script</li>
<li>Optionally, make sure <codeclass="file docutils literal"><spanclass="pre">examples/tests/backend_driver.py</span></code> runs
without errors and check the output of the PNG, PDF, PS and SVG
backends</li>
</ul>
</div>
<divclass="section" id="branching">
<spanid="release-branching"></span><h2>Branching<aclass="headerlink" href="#branching" title="Permalink to this headline">¶</a></h2>
<p>Once all the tests are passing and you are ready to do a release, you
need to create a release branch. These only need to be created when
the second part of the version number changes:</p>
<p>On the branch, do any additional testing you want to do, and then build
binaries and source distributions for testing as release candidates.</p>
<p>For each release candidate as well as for the final release version,
please <codeclass="xref py py-obj docutils literal"><spanclass="pre">git</span><spanclass="pre">tag</span></code> the commit you will use for packaging like so:</p>
<divclass="highlight-python"><divclass="highlight"><pre>git tag -a v1.1.0rc1
</pre></div>
</div>
<p>The <codeclass="xref py py-obj docutils literal"><spanclass="pre">-a</span></code> flag will allow you to write a message about the tag, and
affiliate your name with it. A reasonable tag message would be something
like <codeclass="docutils literal"><spanclass="pre">v1.1.0</span><spanclass="pre">Release</span><spanclass="pre">Candidate</span><spanclass="pre">1</span><spanclass="pre">(September</span><spanclass="pre">24,</span><spanclass="pre">2011)</span></code>. To tag a
release after the fact, just track down the commit hash, and:</p>
<divclass="highlight-python"><divclass="highlight"><pre>git tag -a v1.0.1rc1 a9f3f3a50745
</pre></div>
</div>
<p>Tags allow developers to quickly checkout different releases by name,
and also provides source download via zip and tarball on github.</p>
<spanid="release-packaging"></span><h2>Packaging<aclass="headerlink" href="#packaging" title="Permalink to this headline">¶</a></h2>
<ulclass="simple">
<li>Make sure the <codeclass="file docutils literal"><spanclass="pre">MANIFEST.in</span></code> is up to date and remove
<codeclass="file docutils literal"><spanclass="pre">MANIFEST</span></code> so it will be rebuilt by MANIFEST.in</li>
<li>run <codeclass="xref py py-obj docutils literal"><spanclass="pre">git</span><spanclass="pre">clean</span></code> in the mpl git directory before building the sdist</li>
<li>unpack the sdist and make sure you can build from that directory</li>
<li>Use <codeclass="file docutils literal"><spanclass="pre">setup.cfg</span></code> to set the default backends. For windows and
OSX, the default backend should be TkAgg. You should also turn on
or off any platform specific build options you need. Importantly,
you also need to make sure that you delete the <codeclass="file docutils literal"><spanclass="pre">build</span></code> dir
after any changes to <codeclass="file docutils literal"><spanclass="pre">setup.cfg</span></code> before rebuilding since cruft
in the <codeclass="file docutils literal"><spanclass="pre">build</span></code> dir can get carried along.</li>
<li>On windows, unix2dos the rc file.</li>
<li>We have a Makefile for the OS X builds in the mpl source dir
<codeclass="file docutils literal"><spanclass="pre">release/osx</span></code>, so use this to prepare the OS X releases.</li>
<li>We have a Makefile for the win32 mingw builds in the mpl source dir
<codeclass="file docutils literal"><spanclass="pre">release/win32</span></code> which you can use this to prepare the windows
releases.</li>
</ul>
</div>
<divclass="section" id="posting-files">
<h2>Posting files<aclass="headerlink" href="#posting-files" title="Permalink to this headline">¶</a></h2>
<p>Our current method is for the release manager to collect all of the
binaries from the platform builders and post the files online on
Sourceforge. It is also possible that those building the binaries
could upload to directly to Sourceforge. We also post a source
tarball to PyPI, since <codeclass="docutils literal"><spanclass="pre">pip</span></code> no longer trusts files downloaded from
other sites.</p>
<p>There are many ways to upload files to Sourceforge (<codeclass="xref py py-obj docutils literal"><spanclass="pre">scp</span></code>, <codeclass="xref py py-obj docutils literal"><spanclass="pre">rsync</span></code>,
<codeclass="xref py py-obj docutils literal"><spanclass="pre">sftp</span></code>, and a web interface) described in <aclass="reference external" href="https://sourceforge.net/apps/trac/sourceforge/wiki/Release%20files%20for%20download">Sourceforge Release File
System documentation</a>.
Below, we will use <codeclass="xref py py-obj docutils literal"><spanclass="pre">sftp</span></code>.</p>
<olclass="arabic">
<li><pclass="first">Create a directory containing all of the release files and <codeclass="xref py py-obj docutils literal"><spanclass="pre">cd</span></code> to it.</p>
</li>
<li><pclass="first"><codeclass="xref py py-obj docutils literal"><spanclass="pre">sftp</span></code> to Sourceforge:</p>
<p>If this release is a final release, the default download for the
matplotlib project should also be updated. Login to Sourceforge and
visit the <aclass="reference external" href="https://sourceforge.net/projects/matplotlib/files/matplotlib/">matplotlib files page</a>.
Navigate to the tarball of the release you just updated, click on
“Details” icon (it looks like a lower case <codeclass="docutils literal"><spanclass="pre">i</span></code>), and make it the
default download for all platforms.</p>
<p>There is a list of direct links to downloads on matplotlib’s main
website. This needs to be manually generated and updated every time
new files are posted.</p>
<olclass="arabic">
<li><pclass="first">Clone the matplotlib documentation repository and <codeclass="xref py py-obj docutils literal"><spanclass="pre">cd</span></code> into it:</p>
<li><pclass="first">Update the list of downloads that you want to display by editing
the <codeclass="xref py py-obj docutils literal"><spanclass="pre">downloads.txt</span></code> file. Generally, this should contain the last two
final releases and any active release candidates.</p>
</li>
<li><pclass="first">Update the downloads webpage by running the <codeclass="xref py py-obj docutils literal"><spanclass="pre">update_downloads.py</span></code>
script. This script requires <codeclass="xref py py-obj docutils literal"><spanclass="pre">paramiko</span></code> (for <codeclass="xref py py-obj docutils literal"><spanclass="pre">sftp</span></code> support) and
<codeclass="xref py py-obj docutils literal"><spanclass="pre">jinja2</span></code> for templating. Both of these dependencies can be
<h2>Documentation updates<aclass="headerlink" href="#documentation-updates" title="Permalink to this headline">¶</a></h2>
<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
as well as the bleeding edge release version called <codeclass="xref py py-obj docutils literal"><spanclass="pre">dev</span></code> (usually
based on what’s on master in the github repository, but it may also
temporarily be a staging area for proposed changes). There is also a
symlink directory with the name of the most recently released version
that points to the root. With each new release, these directories may
need to be reorganized accordingly. Any time these version
directories are added or removed, the <codeclass="xref py py-obj docutils literal"><spanclass="pre">versions.html</span></code> file (which
contains a list of the available documentation versions for the user)
must also be updated.</p>
<p>To make sure everyone’s hard work gets credited, regenerate the github
stats. <codeclass="xref py py-obj docutils literal"><spanclass="pre">cd</span></code> into the tools directory and run:</p>