8000 DOC: add release instructions from nibabel · imclab/nipy@3e10563 · GitHub
[go: up one dir, main page]
Skip to content

Commit 3e10563

Browse files
matthew-brettmatthew-brett
committed
DOC: add release instructions from nibabel
They need to be tailored to nipy
1 parent ea3d325 commit 3e10563

File tree

2 files changed

+265
-0
lines changed

2 files changed

+265
-0
lines changed

‎doc/devel/guidelines/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,4 +20,5 @@
2020
debugging
2121
optimization
2222
open_source_devel
23+
make_release
2324
changelog

‎doc/devel/guidelines/make_release.rst

Lines changed: 264 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,264 @@
1+
.. _release-guide:
2+
3+
***********************************
4+
A guide to making a nipy release
5+
***********************************
6+
7+
A guide for developers who are doing a nipy release
8+
9+
.. _release-tools:
10+
11+
Release tools
12+
=============
13+
14+
There are some release utilities that come with nibabel_. nibabel should
15+
install these as the ``nisext`` package, and the testing stuff is understandably
16+
in the ``testers`` module of that package. nipy has Makefile targets for their
17+
use. The relevant targets are::
18+
19+
make check-version-info
20+
make check-files
21+
make sdist-tests
22+
23+
The first installs the code from a git archive, from the repository, and for
24+
in-place use, and runs the ``get_info()`` function to confirm that installation
25+
is working and information parameters are set correctly.
26+
27+
The second (``sdist-tests``) makes an sdist source distribution archive,
28+
installs it to a temporary directory, and runs the tests of that install.
29+
30+
If you have a version of nipy trunk past February 11th 2011, there will also
31+
be a functional make target::
32+
33+
make bdist-egg-tests
34+
35+
This builds an egg (which is a zip file), hatches it (unzips the egg) and runs
36+
the tests from the resulting directory.
37+
38+
.. _release-checklist:
39+
40+
Release checklist
41+
=================
42+
43+
* Review the open list of `nipy issues`_. Check whether there are
44+
outstanding issues that can be closed, and whether there are any issues that
45+
should delay the release. Label them !
46+
47+
* Review and update the release notes. Review and update the :file:`Changelog`
48+
file. Get a partial list of contributors with something like::
49+
50+
git log 0.2.0.. | grep '^Author' | cut -d' ' -f 2- | sort | uniq
51+
52+
where ``0.2.0`` was the last release tag name.
53+
54+
Then manually go over ``git shortlog 0.2.0..`` to make sure the release notes
55+
are as complete as possible and that every contributor was recognized.
56+
57+
* Use the opportunity to update the ``.mailmap`` file if there are any duplicate
58+
authors listed from ``git shortlog``.
59+
60+
* Check the ``long_description`` in ``nipy/info.py``. Check it matches the
61+
``README`` in the root directory.
62+
63+
* Do a final check on the `nipy buildbot`_
64+
65+
* If you have travis-ci_ building set up you might want to push the code in it's
66+
current state to a branch that will build, e.g::
67+
68+
git branch -D pre-release-test # in case branch already exists
69+
git co -b pre-release-test
70+
git push origin pre-release-test
71+
72+
* Clean::
73+
74+
make distclean
75+
76+
* Make sure all tests pass (from the nipy root directory)::
77+
78+
./tools/nipnost -nipy
79+
80+
* Make sure all tests pass from sdist::
81+
82+
make sdist-tests
83+
84+
and bdist_egg::
85+
86+
make bdist-egg-tests
87+
88+
and the three ways of installing (from tarball, repo, local in repo)::
89+
90+
make check-version-info
91+
92+
The last may not raise any errors, but you should detect in the output
93+
lines of this form::
94+
95+
{'sys_version': '2.6.6 (r266:84374, Aug 31 2010, 11:00:51) \n[GCC 4.0.1 (Apple Inc. build 5493)]', 'commit_source': 'archive substitution', 'np_version': '1.5.0', 'commit_hash': '25b4125', 'pkg_path': '/var/folders/jg/jgfZ12ZXHwGSFKD85xLpLk+++TI/-Tmp-/tmpGPiD3E/pylib/nipy', 'sys_executable': '/Library/Frameworks/Python.framework/Versions/2.6/Resources/Python.app/Contents/MacOS/Python', 'sys_platform': 'darwin'}
96+
/var/folders/jg/jgfZ12ZXHwGSFKD85xLpLk+++TI/-Tmp-/tmpGPiD3E/pylib/nipy/__init__.pyc
97+
{'sys_version': '2.6.6 (r266:84374, Aug 31 2010, 11:00:51) \n[GCC 4.0.1 (Apple Inc. build 5493)]', 'commit_source': 'installation', 'np_version': '1.5.0', 'commit_hash': '25b4125', 'pkg_path': '/var/folders/jg/jgfZ12ZXHwGSFKD85xLpLk+++TI/-Tmp-/tmpGPiD3E/pylib/nipy', 'sys_executable': '/Library/Frameworks/Python.framework/Versions/2.6/Resources/Python.app/Contents/MacOS/Python', 'sys_platform': 'darwin'}
98+
/Users/mb312/dev_trees/nipy/nipy/__init__.pyc
99+
{'sys_version': '2.6.6 (r266:84374, Aug 31 2010, 11:00:51) \n[GCC 4.0.1 (Apple Inc. build 5493)]', 'commit_source': 'repository', 'np_version': '1.5.0', 'commit_hash': '25b4125', 'pkg_path': '/Users/mb312/dev_trees/nipy/nipy', 'sys_executable': '/Library/Frameworks/Python.framework/Versions/2.6/Resources/Python.app/Contents/MacOS/Python', 'sys_platform': 'darwin'}
100+
101+
* Check the ``setup.py`` file is picking up all the library code and scripts,
102+
with::
103+
104+
make check-files
105+
106+
Look for output at the end about missed files, such as::
107+
108+
Missed script files: /Users/mb312/dev_trees/nipy/bin/nib-dicomfs, /Users/mb312/dev_trees/nipy/bin/nifti1_diagnose.py
109+
110+
Fix ``setup.py`` to carry across any files that should be in the distribution.
111+
112+
* You probably have virtualenvs for different python versions. Check the tests
113+
pass for different configurations. If you have pytox_ and a network
114+
connnection, and lots of pythons installed, you might be able to do::
115+
116+
tox
117+
118+
and get tests for python 2.5, 2.6, 2.7, 3.2. I (MB) have my own set of
119+
virtualenvs installed and I've set them up to run with::
120+
121+
tox -e python25,python26,python27,python32,np-1.2.1
122+
123+
The trick was only to define these ``testenv`` sections in ``tox.ini``.
124+
125+
These two above run with::
126+
127+
make tox-fresh
128+
make tox-stale
129+
130+
respectively.
131+
132+
The long-hand not-tox way looks like this::
133+
134+
workon python26
135+
make sdist-tests
136+
deactivate
137+
138+
etc for the different virtualenvs.
139+
140+
* Check on different platforms, particularly windows and PPC. I have wine
141+
installed on my Mac, and git bash installed under wine. I run bash and the
142+
tests like this::
143+
144+
wineconsole bash
145+
# in wine bash
146+
make sdist-tests
147+
148+
For the PPC I have to log into an old Mac G5 in Berkeley at
149+
``jerry.bic.berkeley.edu``. Here's an example session::
150+
151+
ssh jerry.bic.berkeley.edu
152+
cd dev_trees/nipy
153+
git co main-master
154+
git pull
155+
make sdist-tests
156+
157+
* Check the documentation doctests::
158+
159+
cd doc
160+
make doctest
161+
cd ..
162+
163+
* Check everything compiles without syntax errors::
164+
165+
python -m compileall .
166+
167+
* The release should now be ready.
168+
169+
* Edit :file:`nipy/info.py` to set ``_version_extra`` to ``''``; commit.
170+
Then::
171+
172+
make source-release
173+
174+
* Once everything looks good, you are ready to upload the source release to
175+
PyPi. See `setuptools intro`_. Make sure you have a file ``\$HOME/.pypirc``,
176+
of form::
177+
178+
[distutils]
179+
index-servers =
180+
pypi
181+
182+
[pypi]
183+
username:your.pypi.username
184+
password:your-password
185+
186+
[server-login]
187+
username:your.pypi.username
188+
password:your-password
189+
190+
* When ready::
191+
192+
python setup.py register
193+
python setup.py sdist --formats=gztar,zip upload
194+
195+
From somewhere - maybe a windows machine - upload the windows installer for
196+
convenience::
197+
198+
python setup.py bdist_wininst upload
199+
200+
* Tag the release with tag of form ``1.1.0``::
201+
202+
git tag -am 'Second main release' 1.1.0
203+
204+
* Now the version number is OK, push the docs to sourceforge with::
205+
206+
make upload-htmldoc-mysfusername
207+
208+
where ``mysfusername`` is obviously your own sourceforge username.
209+
210+
* Set up maintenance / development branches
211+
212+
If this is this is a full release you need to set up two branches, one for
213+
further substantial development (often called 'trunk') and another for
214+
maintenance releases.
215+
216+
* Branch to maintenance::
217+
218+
git co -b maint/0.2.x
219+
220+
Set ``_version_extra`` back to ``.dev`` and bump ``_version_micro`` by 1.
221+
Thus the maintenance series will have version numbers like - say - '0.2.1.dev'
222+
until the next maintenance release - say '0.2.1'. Commit. Don't forget to
223+
push upstream with something like::
224+
225+
git push upstream maint/0.2.x --set-upstream
226+
227+
* Start next development series::
228+
229+
git co main-master
230+
231+
then restore ``.dev`` to ``_version_extra``, and bump ``_version_minor`` by 1.
232+
Thus the development series ('trunk') will have a version number here of
233+
'0.3.0.dev' and the next full release will be '0.3.0'.
234+
235+
If this is just a maintenance release from ``maint/0.2.x`` or similar, just
236+
tag and set the version number to - say - ``0.2.1.dev``.
237+
238+
* Push tags::
239+
240+
git push --tags
241+
242+
* Make next development release tag
243+
244+
After each release the master branch should be tagged
245+
with an annotated (or/and signed) tag, naming the intended
246+
next version, plus an 'upstream/' prefix and 'dev' suffix.
247+
For example 'upstream/1.0.0.dev' means "development start
248+
for upcoming version 1.0.0.
249+
250+
This tag is used in the Makefile rules to create development snapshot
251+
releases to create proper versions for those. The version derives its name
252+
from the last available annotated tag, the number of commits since that, and
253+
an abbreviated SHA1. See the docs of ``git describe`` for more info.
254+
255+
Please take a look at the Makefile rules ``devel-src``,
256+
``devel-dsc`` and ``orig-src``.
257+
258+
* Announce to the mailing lists.
259+
260+
.. _pytox: http://codespeak.net/tox
261+
.. _setuptools intro: http://packages.python.org/an_example_pypi_project/setuptools.html
262+
.. _travis-ci: http://travis-ci.org
263+
264+
.. include:: ../../links_names.txt

0 commit comments

Comments
 (0)
0