Skip to content

Commit 07f6427

Browse files
tacaswelltacaswell
committed
Merge branch 'v2.x'
Conflicts: doc/devel/MEP/MEP12.rst - discarded whitespace changes doc/devel/release_guide.rst - kept version from 2.x doc/mpl_toolkits/index.rst - kept master version (due to re-organization)
2 parents c4fb1f2 + dba5232 commit 07f6427

File tree

6 files changed

+387
-209
lines changed

6 files changed

+387
-209
lines changed

‎doc/devel/release_guide.rst

+210-106
Original file line numberDiff line numberDiff line change
@@ -1,169 +1,273 @@
1+
.. highlight:: bash
2+
13
.. _release-guide:
24

3-
*************
4-
Release Guide
5-
*************
5+
===============
6+
Release Guide
7+
===============
68

79
A guide for developers who are doing a matplotlib release.
810

9-
* Edit :file:`__init__.py` and bump the version number
11+
All Releases
12+
============
1013

1114
.. _release-testing:
1215

1316
Testing
14-
=======
17+
-------
18+
19+
We use `travis-ci <https://travis-ci.org/matplotlib/matplotlib>`__ for
20+
continuous integration. When preparing for a release, the final
21+
tagged commit should be tested locally before it is uploaded::
22+
23+
python tests.py --processes=8 --process-timeout=300
24+
25+
In addition the following two tests should be run and manually inspected::
26+
27+
python unit/memleak_hawaii3.py
28+
pushd examples/tests/
29+
python backend_driver.py
30+
popd
31+
32+
33+
.. _release_ghstats:
34+
35+
GitHub Stats
36+
------------
37+
38+
We automatically extract GitHub issue, PRs, and authors from GitHub via the API::
39+
40+
python tools/github_stats.py --since-tag $TAG --project 'matplotlib/matplotlib' --links > doc/users/github_stats.rst
41+
42+
Review and commit changes. Some issue/PR titles may not be valid rst (the most common issue is
43+
``*`` which is interpreted as unclosed markup).
44+
45+
46+
.. _release_chkdocs:
47+
48+
Check Docs
49+
----------
50+
51+
Before tagging, make sure that the docs build cleanly ::
52+
53+
pushd doc
54+
python make.py html latex -n 16
55+
popd
56+
57+
After the docs are built, check that all of the links, internal and external, are still
58+
valid. We use ``linkchecker`` for this, which has not been ported to python3 yet. You will
59+
need to create a python2 environment with ``requests==2.9.0`` and linkchecker ::
60+
61+
conda create -p /tmp/lnkchk python=2 requests==2.9.0
62+
source activate /tmp/lnkchk
63+
pip install linkchecker
64+
pushd doc/build/html
65+
linkchecker index.html --check-extern
1566

16-
* Run all of the regression tests by running ``python tests.py``
17-
at the root of the source tree.
67+
Address any issues which may arise. The internal links are checked on travis, this should only
68+
flag failed external links.
1869

19-
* Run :file:`unit/memleak_hawaii3.py` and make sure there are no
20-
memory leaks
70+
.. _release_tag:
2171

22-
* try some GUI examples, e.g., :file:`simple_plot.py` with GTKAgg, TkAgg, etc...
72+
Create release commit and tag
73+
-----------------------------
2374

24-
* remove font cache and tex cache from :file:`.matplotlib` and test
25-
with and without cache on some example script
75+
To create the tag, first create an empty commit with a very terse set of the release notes
76+
in the commit message ::
2677

27-
* Optionally, make sure :file:`examples/tests/backend_driver.py` runs
28-
without errors and check the output of the PNG, PDF, PS and SVG
29-
backends
78+
git commit --allow-empty
3079

31-
.. _release-branching:
80+
and then create a signed, annotated tag with the same text in the body
81+
message ::
3282

33-
Branching
34-
=========
83+
git tag -a -s v2.0.0
3584

36-
Once all the tests are passing and you are ready to do a release, you
37-
need to create a release branch. These only need to be created when
38-
the second part of the version number changes::
85+
which will prompt you for your gpg key password and an annotation.
86+
For pre releases it is important to follow :pep:`440` so that the
87+
build artifacts will sort correctly in pypi. Finally, push the tag to GitHub ::
3988

40-
git checkout -b v1.1.x
41-
git push [email protected]:matplotlib/matplotlib.git v1.1.x
89+
git push -t DANGER v2.0.0
4290

43-
On the branch, do any additional testing you want to do, and then build
44-
binaries and source distributions for testing as release candidates.
91+
Congratulations, the scariest part is done!
4592

46-
For each release candidate as well as for the final release version,
47-
please `git tag` the commit you will use for packaging like so::
93+
To prevent issues with any down-stream builders which download the
94+
tarball from GitHub it is important to move all branches away from the commit
95+
with the tag [#]_::
4896

49-
git tag -a v1.1.0rc1
97+
git commit --allow-empty
98+
git push DANGER master
5099

51-
The `-a` flag will allow you to write a message about the tag, and
52-
affiliate your name with it. A reasonable tag message would be something
53-
like ``v1.1.0 Release Candidate 1 (September 24, 2011)``. To tag a
54-
release after the fact, just track down the commit hash, and::
55100

56-
git tag -a v1.0.1rc1 a9f3f3a50745
101+
.. [#] The tarball that is provided by GitHub is produced using `git
102+
archive <https://git-scm.com/docs/git-archive>`__. We use
103+
`versioneer <https://github.com/warner/python-versioneer>`__
104+
which uses a format string in
105+
:file:`lib/matplotlib/_version.py` to have ``git`` insert a
106+
list of references to exported commit (see
107+
:file:`.gitattributes` for the configuration). This string is
108+
then used by ``versioneer`` to produce the correct version,
109+
based on the git tag, when users install from the tarball.
110+
However, if there is a branch pointed at the tagged commit,
111+
then the branch name will also be included in the tarball.
112+
When the branch eventually moves, anyone how checked the hash
113+
of the tarball before the branch moved will have an incorrect
114+
hash.
57115
58-
Tags allow developers to quickly checkout different releases by name,
59-
and also provides source download via zip and tarball on github.
116+
To generate the file that GitHub does use ::
60117
61-
Then push the tags to the main repository::
118+
git archive v2.0.0 -o matplotlib-2.0.0.tar.gz --prefix=matplotlib-2.0.0/
62119
63-
git push upstream v1.0.1rc1
64120
65-
.. _release-packaging:
121+
If this is a final release, also create a 'doc' branch (this is not
122+
done for pre-releases)::
66123

67-
Packaging
68-
=========
124+
git branch v2.0.0-doc
125+
git push DANGER v2.0.0-doc
69126

70-
* Make sure the :file:`MANIFEST.in` is up to date and remove
71-
:file:`MANIFEST` so it will be rebuilt by MANIFEST.in
127+
and if this is a major or minor release, also create a bug-fix branch (a
128+
micro release will be cut off of this branch)::
72129

73-
* run `git clean` in the mpl git directory before building the sdist
130+
git branch v2.0.x
131+
git push DANGER v2.0.x
74132

75-
* unpack the sdist and make sure you can build from that directory
76133

77-
* Use :file:`setup.cfg` to set the default backends. For windows and
78-
OSX, the default backend should be TkAgg. You should also turn on
79-
or off any platform specific build options you need. Importantly,
80-
you also need to make sure that you delete the :file:`build` dir
81-
after any changes to :file:`setup.cfg` before rebuilding since cruft
82-
in the :file:`build` dir can get carried along.
83134

84-
* On windows, unix2dos the rc file.
135+
.. _release_DOI:
85136

86-
* We have a Makefile for the OS X builds in the mpl source dir
87-
:file:`release/osx`, so use this to prepare the OS X releases.
137+
Release Management / DOI
138+
------------------------
88139

89-
* We have a Makefile for the win32 mingw builds in the mpl source dir
90-
:file:`release/win32` which you can use this to prepare the windows
91-
releases.
140+
Via the GitHub UI (chase down link), turn the newly pushed tag into a
141+
release. If this is a pre-release remember to mark it as such.
92142

143+
For final releases also get a DOI from `zenodo
144+
<https://zenodo.org/>`__ and edit :file:`doc/_templates/citing.html`
145+
with DOI link and commit to the VER-doc branch and push to GitHub ::
93146

94-
Update PyPI
95-
===========
147+
git checkout v2.0.0-doc
148+
emacs doc/_templates/citing.html
149+
git push DANGER v2.0.0-doc:v2.0.0-doc
96150

97-
This step tells PyPI about the release and uploads a source
98-
tarball. This should only be done with final (non-release-candidate)
99-
releases, since doing so will hide any available stable releases.
151+
.. _release_bld_bin:
100152

101-
You may need to set up your `.pypirc` file as described in the
102-
`distutils register command documentation
103-
<https://docs.python.org/3/distutils/packageindex.html>`_.
153+
Building binaries
154+
-----------------
104155

105-
Then updating the record on PyPI is as simple as::
156+
We distribute mac, windows, and many linux wheels as well as a source
157+
tarball via pypi. Before uploading anything, contact the various
158+
builders. Mac and manylinux wheels are built on travis . You need to
159+
edit the :file:`.travis.yml` file and push to master of `the build
160+
project <https://github.com/MacPython/matplotlib-wheels>`__.
106161

107-
python setup.py register
162+
Update the ``master`` branch (for pre-releases the ``devel`` branch)
163+
of the `conda-forge feedstock
164+
<https://github.com/conda-forge/matplotlib-feedstock>`__ via pull request.
108165

109-
This will hide any previous releases automatically.
166+
If this is a final release the following downstream packagers should be contacted:
110167

111-
Then, to upload the source tarball::
168+
- Debian
169+
- Fedora
170+
- Arch
171+
- Gentoo
172+
- Macports
173+
- Homebrew
174+
- Christoph Gohlke
175+
- Continuum
176+
- Enthought
112177

113-
rm -rf dist
114-
python setup.py sdist upload
178+
This can be done ahead of collecting all of the binaries and uploading to pypi.
179+
180+
.. _release_upload_bin:
181+
182+
make distribution and upload to pypi / SF
183+
-----------------------------------------
184+
185+
Once you have collected all of the wheels, generate the tarball ::
186+
187+
git checkout v2.0.0
188+
git clean -xfd
189+
python setup.py sdist
190+
191+
and copy all of the wheels into :file:`dist` directory. You should use
192+
``twine`` to upload all of the files to pypi ::
193+
194+
twine upload -s dist/matplotlib*tar.gz
195+
twine upload dist/*whl
196+
197+
Congratulations, you have now done the second scariest part!
198+
199+
Additionally, for a final release, upload all of the files to sourceforge.
200+
201+
.. _release_docs:
202+
203+
Build and Deploy Documentation
204+
------------------------------
205+
206+
To build the documentation you must have the tagged version installed, but
207+
build the docs from the ``ver-doc`` branch. An easy way to arrange this is::
208+
209+
pip install matplotlib
210+
pip install -r doc-requirements.txt
211+
git checkout v2.0.0-doc
212+
git clean -xfd
213+
cd doc
214+
python make.py html latex -n 16
215+
216+
which will build both the html and pdf version of the documentation.
115217

116-
Documentation updates
117-
=====================
118218

119219
The built documentation exists in the `matplotlib.github.com
120-
<https://github.com/matplotlib/matplotlib.github.com/>`_ repository.
220+
<https://github.com/matplotlib/matplotlib.github.com/>`__ repository.
121221
Pushing changes to master automatically updates the website.
122222

123223
The documentation is organized by version. At the root of the tree is
124224
always the documentation for the latest stable release. Under that,
125-
there are directories containing the documentation for older versions
126-
as well as the bleeding edge release version called `dev` (usually
127-
based on what's on master in the github repository, but it may also
128-
temporarily be a staging area for proposed changes). There is also a
129-
symlink directory with the name of the most recently released version
130-
that points to the root. With each new release, these directories may
131-
need to be reorganized accordingly. Any time these version
132-
directories are added or removed, the `versions.html` file (which
133-
contains a list of the available documentation versions for the user)
134-
must also be updated.
225+
there are directories containing the documentation for older versions.
226+
The documentation for current master are built on travis and push to
227+
the `devdocs <https://github.com/matplotlib/devdocs/>`__ repository.
228+
These are available at `matplotlib.org/devdocs
229+
<http://matplotlib.org/devdocs>`__.
135230

136-
To make sure everyone's hard work gets credited, regenerate the github
137-
stats. `cd` into the tools directory and run::
231+
Assuming you have this repository checked out in the same directory as
232+
matplotlib ::
138233

139-
python github_stats.py $TAG > ../doc/users/github_stats.rst
234+
cd ../matplotlib.github.com
235+
mkdir 2.0.0
236+
rsync -a ../matplotlib/doc/build/html/* 2.0.0
237+
cp ../matplotlib/doc/build/latex/Matplotlib.pdf 2.0.0
140238

141-
where `$TAG` is the tag of the last major release. This will generate
142-
stats for all work done since that release.
239+
which will copy the built docs over. If this is a final release, also
240+
replace the top-level docs ::
143241

144-
In the matplotlib source repository, build the documentation::
242+
rsync -a 2.0.0/* ./
145243

146-
cd doc
147-
python make.py html
148-
python make.py latex
244+
You will need to manually edit :file:`versions.html` to show the last
245+
3 tagged versions. Now commit and push everything to GitHub ::
149246

150-
Then copy the build products into your local checkout of the
151-
`matplotlib.github.com` repository (assuming here to be checked out in
152-
`~/matplotlib.github.com`::
247+
git add *
248+
git commit -a -m 'Updating docs for v2.0.0'
249+
git push DANGER master
153250

154-
cp -r build/html/* ~/matplotlib.github.com
155-
cp build/latex/Matplotlib.pdf ~/matplotlib.github.com
251+
Congratulations you have now done the third scariest part!
156252

157-
Then, from the `matplotlib.github.com` directory, commit and push the
158-
changes upstream::
253+
It typically takes about 5-10 minutes for GitHub to process the push
254+
and update the live web page (remember to clear your browser cache).
159255

160-
git commit -m "Updating for v1.0.1"
161-
git push upstream master
162256

163257
Announcing
164-
==========
258+
----------
259+
260+
The final step is to announce the release to the world. A short
261+
version of the release notes along with acknowledgments should be sent to
262+
263+
- [email protected]
264+
- [email protected]
265+
- [email protected]
266+
267+
For final releases announcements should also be sent to the
268+
numpy/scipy/jupyter mailing lists and python-announce.
165269

166-
Announce the release on matplotlib-announce, matplotlib-users, and
167-
matplotlib-devel. Final (non-release-candidate) versions should also
168-
be announced on python-announce. Include a summary of highlights from
169-
the CHANGELOG and/or post the whole CHANGELOG since the last release.
270+
In addition, announcements should be made on social networks (twitter,
271+
g+, FB). For major release, `NumFOCUS <http://www.numfocus.org/>`__
272+
should be contacted for inclusion in their newsletter and maybe to
273+
have something posted on their blog.

0 commit comments

Comments
 (0)