4
4
Doing a matplotlib release
5
5
*************************
6
6
7
- A guide for developers who are doing a matplotlib release
7
+ A guide for developers who are doing a matplotlib release.
8
8
9
9
* Edit :file: `__init__.py ` and bump the version number
10
10
@@ -34,7 +34,8 @@ Branching
34
34
=========
35
35
36
36
Once all the tests are passing and you are ready to do a release, you
37
- need to create a release branch::
37
+ need to create a release branch. These only need to be created when
38
+ the second part of the version number changes::
38
39
39
40
git checkout -b v1.1.x
40
41
git push git@github.com:matplotlib/matplotlib.git v1.1.x
@@ -52,14 +53,14 @@ affiliate your name with it. A reasonable tag message would be something
52
53
like ``v1.1.0 Release Candidate 1 (September 24, 2011) ``. To tag a
53
54
release after the fact, just track down the commit hash, and::
54
55
55
- git tag -a v1.0.1 a9f3f3a50745
56
+ git tag -a v1.0.1rc1 a9f3f3a50745
56
57
57
58
Tags allow developers to quickly checkout different releases by name,
58
59
and also provides source download via zip and tarball on github.
59
60
60
61
Then push the tags to the main repository::
61
62
62
- git push upstream v1.0.1
63
+ git push upstream v1.0.1rc1
63
64
64
65
.. _release-packaging :
65
66
@@ -80,7 +81,7 @@ Packaging
80
81
after any changes to :file: `setup.cfg ` before rebuilding since cruft
81
82
in the :file: `build ` dir can get carried along.
82
83
83
- * on windows, unix2dos the rc file
84
+ * On windows, unix2dos the rc file.
84
85
85
86
* We have a Makefile for the OS X builds in the mpl source dir
86
87
:file: `release/osx `, so use this to prepare the OS X releases.
@@ -89,17 +90,92 @@ Packaging
89
90
:file: `release/win32 ` which you can use this to prepare the windows
90
91
releases.
91
92
92
- .. _release-candidate-testing :
93
+ Posting files
94
+ =============
93
95
94
- Release candidate testing
95
- =========================
96
+ Our current method is for the release manager to collect all of the
97
+ binaries from the platform builders and post the files online on
98
+ Sourceforge. It is also possible that those building the binaries
99
+ could upload to directly to Sourceforge.
96
100
97
- Post the release candidates tarballs to the `matplotlib download page
98
- <https://github.com/matplotlib/matplotlib/downloads> `_. If you have
99
- developer rights, you should see an "Upload a new file" section
100
- there.
101
+ There are many ways to upload files to Sourceforge (`scp `, `rsync `,
102
+ `sftp `, and a web interface) described in `Sourceforge Release File
103
+ System documentation
104
+ <https://sourceforge.net/apps/trac/sourceforge/wiki/Release%20files%20for%20download> `_.
105
+ Below, we will use `sftp `.
101
106
102
- .. _release-announcing :
107
+ 1. Create a directory containing all of the release files and `cd ` to it.
108
+
109
+ 2. `sftp ` to Sourceforge::
110
+
111
+ sftp USERNAME@frs.sourceforge.net:/home/frs/project/matplotlib/matplotlib
112
+
113
+ 3. Make a new directory for the release and move to it::
114
+
115
+ mkdir matplotlib-1.1.0rc1
116
+ cd matplotlib-1.1.0rc1
117
+
118
+ 4. Upload all of the files in the current directory on your local machine::
119
+
120
+ put *
121
+
122
+ If this release is a final release, the default download for the
123
+ matplotlib project should also be updated. Login to Sourceforge and
124
+ visit the `matplotlib files page
125
+ <https://sourceforge.net/projects/matplotlib/files/matplotlib/> `_.
126
+ Navigate to the tarball of the release you just updated, click on
127
+ "Details" icon (it looks like a lower case ``i ``), and make it the
128
+ default download for all platforms.
129
+
130
+ There is a list of direct links to downloads on matplotlib's main
131
+ website. This needs to be manually generated and updated every time
132
+ new files are posted.
133
+
134
+ 1. Clone the matplotlib documentation repository and `cd ` into it::
135
+
136
+ git clone git@github.com:matplotlib/matplotlib.github.com.git
137
+ cd matplotlib.github.com
138
+
139
+ 2. Update the list of downloads that you want to display by editing
140
+ the `downloads.txt ` file. Generally, this should contain the last two
141
+ final releases and any active release candidates.
142
+
143
+ 3. Update the downloads webpage by running the `update_downloads.py `
144
+ script. This script requires `paramiko ` (for `sftp ` support) and
145
+ `jinja2 ` for templating. Both of these dependencies can be
146
+ installed using pip::
147
+
148
+ pip install paramiko
149
+ pip install jinja2
150
+
151
+ Then update the download page::
152
+
153
+ ./update_downloads.py
154
+
155
+ You will be prompted for your Sourceforge username and password.
156
+
157
+ 4. Commit the changes and push them up to github::
158
+
159
+ git commit -m "Updating download list"
160
+ git push
161
+
162
+ Update PyPI
163
+ ===========
164
+
165
+ Once the tarball has been posted on Sourceforge, you can register a
166
+ link to the new release on PyPI. This should only be done with final
167
+ (non-release-candidate) releases, since doing so will hide any
168
+ available stable releases.
169
+
170
+ You may need to set up your `.pypirc ` file as described in the
171
+ `distutils register command documentation
172
+ <http://docs.python.org/2/distutils/packageindex.html> `_.
173
+
174
+ Then updating the record on PyPI is as simple as::
175
+
176
+ python setup.py register
177
+
178
+ This will hide any previous releases automatically.
103
179
104
180
Documentation updates
105
181
=====================
@@ -108,6 +184,27 @@ The built documentation exists in the `matplotlib.github.com
108
184
<https://github.com/matplotlib/matplotlib.github.com/> `_ repository.
109
185
Pushing changes to master automatically updates the website.
110
186
187
+ The documentation is organized by version. At the root of the tree is
188
+ always the documentation for the latest stable release. Under that,
189
+ there are directories containing the documentation for older versions
190
+ as well as the bleeding edge release version called `dev ` (usually
191
+ based on what's on master in the github repository, but it may also
192
+ temporarily be a staging area for proposed changes). There is also a
193
+ symlink directory with the name of the most recently released version
194
+ that points to the root. With each new release, these directories may
195
+ need to be reorganized accordingly. Any time these version
196
+ directories are added or removed, the `versions.html ` file (which
197
+ contains a list of the available documentation versions for the user)
198
+ must also be updated.
199
+
200
+ To make sure everyone's hard work gets credited, regenerate the github
201
+ stats. `cd ` into the tools directory and run::
202
+
203
+ python github_stats.py $TAG > ../doc/users/github_stats.rst
204
+
205
+ where `$TAG ` is the tag of the last major release. This will generate
206
+ stats for all work done since that release.
207
+
111
208
In the matplotlib source repository, build the documentation::
112
209
113
210
cd doc
@@ -130,6 +227,7 @@ changes upstream::
130
227
Announcing
131
228
==========
132
229
133
- Announce the release on matplotlib-announce, matplotlib-users and
134
- matplotlib-devel. Include a summary of highlights from the CHANGELOG
135
- and/or post the whole CHANGELOG since the last release.
230
+ Announce the release on matplotlib-announce, matplotlib-users, and
231
+ matplotlib-devel. Final (non-release-candidate) versions should also
232
+ be announced on python-announce. Include a summary of highlights from
233
+ the CHANGELOG and/or post the whole CHANGELOG since the last release.
0 commit comments