/
release.txt
236 lines (169 loc) · 7.67 KB
/
release.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
.. vim: set filetype=rst
================================
Releasing a new version of khmer
================================
How to make a khmer release candidate
-------------------------------------
Michael R. Crusoe, Luiz Irber, and C. Titus Brown have all been
release makers, following this checklist by MRC.
#. The below should be done in a clean checkout::
cd `mktemp -d`
git clone git@github.com:ged-lab/khmer.git
cd khmer
#. (Optional) Check for updates to versioneer::
pip install versioneer
versioneer-installer
git diff
./setup.py versioneer
git diff
git commit -m -a "new version of versioneer.py"
# or
git checkout -- versioneer.py khmer/_version.py khmer/__init__.py MANIFEST.in
#. Review the git logs since the last release and diffs (if needed) and ensure
that the ``ChangeLog`` is up to date::
git log --minimal --patch `git describe --tags --always --abbrev=0`..HEAD
#. Review the issue list for any new bugs that will not be fixed in this
release. Add them to ``doc/known-issues.txt``
#. Verify that the build is clean: http://ci.ged.msu.edu/job/khmer-master/
#. Submit a build to Coverity Scan if it hasn't been done
recently. You can get the token from
https://gitlab.msu.edu/ged-lab/ged-internal-docs/wikis/coverity-scan
or https://scan.coverity.com/projects/621?tab=project_settings
::
make clean
cov_analysis_dir=~/src/coverity/cov-analysis-linux64-7.0.2/ make coverity-build
COVERITY_TOKEN=${COVERITY_TOKEN} make coverity-upload
#. Set your new version number and release candidate::
new_version=1.1
rc=rc3
and then tag the release candidate with the new version number prefixed by
the letter 'v'::
git tag v${new_version}-${rc}
git push --tags git@github.com:ged-lab/khmer.git
#. Test the release candidate. Bonus: repeat on Mac OS X::
cd ..
virtualenv testenv1
virtualenv testenv2
virtualenv testenv3
virtualenv testenv4
# First we test the tag
cd testenv1
source bin/activate
git clone --depth 1 --branch v${new_version}-${rc} https://github.com/ged-lab/khmer.git
cd khmer
make install
make test
normalize-by-median.py --version # double-check version number
# Secondly we test via pip
cd ../../testenv2
source bin/activate
pip install -U setuptools==3.4.1
pip install -e git+https://github.com/ged-lab/khmer.git@v${new_version}-${rc}#egg=khmer
cd src/khmer
make dist
make install
make test
normalize-by-median.py --version # double-check version number
cp dist/khmer*tar.gz ../../../testenv3/
# Is the distribution in testenv2 complete enough to build another
# functional distribution?
cd ../../../testenv3/
source bin/activate
pip install -U setuptools==3.4.1
pip install khmer*tar.gz
tar xzf khmer*tar.gz
cd khmer*
make dist
make test
#. Publish the new release on the testing PyPI server. You will need
to change your PyPI credentials as documented here:
https://wiki.python.org/moin/TestPyPI. You may need to re-register::
python setup.py register --repository test
Now, upload the new release::
python setup.py sdist upload -r test
Test the PyPI release in a new virtualenv::
cd ../../testenv4
source bin/activate
pip install -U setuptools==3.4.1
pip install screed nose
pip install -i https://testpypi.python.org/pypi --pre --no-clean khmer
normalize-by-median.py --version 2>&1 | awk ' { print $2 } '
cd build/khmer
./setup.py nosetests
#. Do any final testing (BaTLab and/or acceptance tests).
#. Make sure any release notes are merged into doc/release-notes/.
How to make a final release
---------------------------
When you've got a thoroughly tested release candidate, cut a release like
so:
#. Create the final tag and publish the new release on PyPI (requires an
authorized account).::
cd ../../../khmer
git tag v${new_version}
python setup.py register sdist upload
#. Delete the release candidate tag and push the tag updates to GitHub.::
git tag -d v${new_version}-${rc}
git push git@github.com:ged-lab/khmer.git
git push --tags git@github.com:ged-lab/khmer.git
#. Add the release on GitHub, using the tag you just pushed. Name
it 'version X.Y.Z', and copy and paste in the release notes.
#. Make a binary wheel on OS X.::
virtualenv build
cd build
source bin/activate
pip install -U setuptools==3.4.1 wheel
pip install --no-clean khmer==${new_version}
cd build/khmer
./setup.py bdist_wheel upload
#. Update Read the Docs to point to the new version. Visit
https://readthedocs.org/builds/khmer/ and 'Build Version: master' to pick up
the new tag. Once that build has finished check the "Activate" box next to
the new version at https://readthedocs.org/dashboard/khmer/versions/ under
"Choose Active Versions". Finally change the default version at
https://readthedocs.org/dashboard/khmer/advanced/ to the new version.
#. Delete any RC tags created::
git tag -d ${new_version}-${rc}
git push origin :refs/tags/${new_version}-${rc}
#. Tweet about the new release.
#. Send email including the release notes to khmer@lists.idyll.org
and khmer-announce@lists.idyll.org
BaTLab testing
--------------
The UW-Madison Build and Test Lab provides the khmer project with a free
cross-platform testing environment.
#. Connect to their head node::
ssh mcrusoe@submit-1.batlab.org
#. Move into the khmer directory and download a release from PyPI's main server
or the test PyPI server::
cd khmer/
wget https://testpypi.python.org/packages/source/k/khmer/khmer-1.0.1-rc3.tar.gz
vim khmer-v1.0.inputs # change the 'scp_file' to point to the release
vim khmer-v1.0.run-spec # change 'project_version' at bottom
nmi_submit khmer-v1.0.run-spec
Setuptools Bootstrap
--------------------
ez_setup.py is from https://bitbucket.org/pypa/setuptools/raw/bootstrap/
Before major releases it should be examined to see if there are new
versions available and if the change would be useful
Versioning Explanation
----------------------
Versioneer, from https://github.com/warner/python-versioneer, is used to
determine the version number and is called by Setuptools and Sphinx. See the
files ``versioneer.py``, the top of ``khmer/__init__.py``,
``khmer/_version.py``, ``setup.py``, and ``doc/conf.py`` for the
implementation.
The version number is determined through several methods: see
https://github.com/warner/python-versioneer#version-identifiers
If the source tree is from a git checkout then the version number is derived by
``git describe --tags --dirty --always``. This will be in the format
``${tagVersion}-${commits_ahead}-${revision_id}-${isDirty}``. Example:
``v0.6.1-18-g8a9e430-dirty``
If from an unpacked tarball then the name of the directory is queried.
Lacking either of the two git-archive will record the version number at the top
of ``khmer/_version.py`` via the ``$Format:%d$`` and ``$Format:%H$``
placeholders enabled by the "export-subst" entry in ``.gitattributes``.
Non source distributions will have a customized ``khmer/_version.py`` that
contains hard-coded version strings. (see ``build/*/khmer/_version.py`` after a
``python setup.py build`` for an example)
``ez_setup.py`` bootstraps Setuptools (if needed) by downloading and installing
an appropriate version