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
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
|
=============================
Docutils_ Release Procedure
=============================
:Authors: David Goodger; Lea Wiemann; open to all Docutils developers
:Contact: docutils-develop@lists.sourceforge.net
:Date: $Date$
:Revision: $Revision$
:Copyright: This document has been placed in the public domain.
.. _Docutils: http://docutils.sourceforge.net/
Assumptions and their failure
-----------------------------
On the test machine python 2.6, 2.7 and 3.2, 3.3, and 3.4
are installed.
Some in /usr/ some under /usr/local.
Assumption: If python2.6 is in /usr/bin/ then site-packages is under
/usr/local/lib/python2.6.
On new ubuntu 12.10
* python2.7 is here /usr/bin/python2.7.
* in /usr/lib are python2.7, pymodules and pyshared.
in /usr/lib/python2.7 no site-packages directory even after installation
of docutils
in /usr/local/lib/python2.7 are dist-packages site-packages.
site-packages is empty.
docutils is installed under dist-packages.
pymodules has a python2.7 directory.
Releasing
---------
Version identifier
~~~~~~~~~~~~~~~~~~
For details, see `Version Numbering in Docutils Project Policies`__.
__ policies.html#version-numbering
How to change the version identifier
""""""""""""""""""""""""""""""""""""
The *version identifier* ``docutils.__version__`` is defined in
``docutils/docutils/__init__.py`` and used in in the following files::
docutils/setup.py
docutils/test/functional/expected/* ("Generator: Docutils X.Y[.Z]")
docutils/README.txt
web/index.txt
You can use the script ``set_release.sh`` to change the version
identifier:
#. ``cd`` to the "docutils" subdirectory in the repository checkout,
#. call ::
../sandbox/infrastructure/set_release.sh <new_version>
where ``<new_version>`` is major.minor[.micro][<pre>][.dev].
This also changes ``__version_info__`` in
``docutils/docutils/__init__.py``.
Run the test suite after changing the codebase version to ensure
accuracy and consistency.
Release steps
~~~~~~~~~~~~~
REWORK FOR SOURCEFORGE REPO
.. WARNING:: Steps in boldface text are *not* covered by the release script
at sandbox/infrastructure/release.sh. "Not covered" means that you
aren't even reminded of them.
.. Note:: This document does not cover branching and tagging, but the
release script does.
.. Note:: You may want to use ReleaseForge_ instead of using
SourceForge's file release system.
.. _ReleaseForge: http://releaseforge.sourceforge.net/
* **Announce**
On the Docutils-develop mailing list, announce that the release is
going to be made, update the release notes (consult HISTORY.TXT for
changes) and ask for additions.
Announce the upcoming release at the Sphinx-devel mailing list
and ask for testing with Sphinx.
(This step can be skipped for bugfix releases and pre-releases.)
Announce the date of the feature freeze – at least a week ahead!
* **Feature freeze** From now on, only bug-fix commits are allowed.
Update the `pre-release segment` of the `version identifier`_
(``b``, ``rcN`` or empty) to match the level of the upcoming release
(beta, candidate or final). Ensure ``docutils.__version_info__`` matches
the version identifier. (See also `How to change the version
identifier`_.)
* **Announce** the check-in freeze date on Docutils-develop – at least a
week ahead.
* **Check-in freeze**
**Update the version identifier**:
Remove the `development release segment` (``.dev``) from the `version
identifier`_ and set ``docutils.__version_info__.release`` to True.
Check the `version identifier` in the following files (should be
already correct if set according to `How to change the version
identifier`_):
+ docutils/setup.py
+ docutils/docutils/__init__.py
+ docutils/test/functional/expected/* ("Generator: Docutils X.Y[.Z]")
+ docutils/README.txt
+ web/index.txt
* See what ``sandbox/infrastructure/release.sh`` can aid
.. Note:: *BUG* test tarball requires root password, but it is possible to
skip this stage interactively, and testing should be done before
release.
* Close the "Changes Since ..." section in docutils/HISTORY.txt.
* Clear/unset the PYTHONPATH environment variable.
* Create the release tarball:
(a) Create a new empty directory and ``cd`` into it.
(b) Get a clean snapshot of the main tree::
svn export svn://svn.code.sf.net/p/docutils/code/trunk/docutils
or via the [Download Snapshot] button at
http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
(c) Use Distutils to create the release tarball::
cd docutils
python setup.py sdist
* Expand and _`install` the release tarball in isolation:
(a) Expand the tarball in a new location, not over any existing
files.
(b) Remove the old installation from site-packages (including
roman.py, and optparse.py, textwrap.py).
"remove" might fail, see _`Assumptions and their failure`
Install from expanded directory::
cd docutils-X.Y.Z
python setup.py install
The "install" command may require root permissions.
(c) Repeat step b) for all supported Python versions.
* Run the _`test suite` from the expanded archive directory with all
supported Python versions on all available platforms (GNU/Linux, Mac
OS X, Windows)::
cd test ; python -u alltests.py
* Add a directory X.Y.Z (where X.Y.Z is the current version number
of Docutils) in the webroot (i.e. the ``htdocs/`` directory).
Put all documentation files into it::
cd docutils-X.Y.Z
rm -rf build
cd tools/
./buildhtml.py ..
cd ..
find -name test -type d -prune -o -name \*.css -print0 \
-o -name \*.html -print0 -o -name \*.txt -print0 \
| tar -cjvf docutils-docs.tar.bz2 -T - --null
scp docutils-docs.tar.bz2 <username>@shell.sourceforge.net:
Now log in to shell.sourceforge.net and::
cd /home/groups/d/do/docutils/htdocs/
mkdir -m g+rwxs X.Y.Z
cd X.Y.Z
tar -xjvf ~/docutils-docs.tar.bz2
rm ~/docutils-docs.tar.bz2
* Upload the release tarball, release.sh tries with scp.
* Access the _`file release system` on SourceForge (Admin
interface).
``https://sourceforge.net/projects/docutils/files/docutils/``
* change into the released version's directory
* click ``(i)`` button of the tar.gz-file
* select as default download for all operating systems.
* Submit a notification on project news.
* For verifying the integrity of the release, download the release
tarball (you may need to wait up to 30 minutes), install_ it, and
re-run the `test suite`_.
* Register with PyPI (``python setup.py register``).
Set the download-url so eggs can access older releases.
* **build wheels**::
pip wheel docutils
pip3 wheel docutils
This builds wheels_ (`pure Python wheels`_ for Python 2 and 3
respectively) by downloading the new release from pypi.
Upload the wheels to PyPI::
twine upload docultils-<VERSION>-py2-none-any.whl
twine upload wheelhouse/docultils-<VERSION>-py3-none-any.whl
* **Lift the freeze**
Set the `version identifier`_ and ``__version_info__.releaselevel`` in
docutils/docutils/__init__.py to mark the repository version as
"in development", usually ``<major>.<minor+1>b.dev`` (cf. `How to change
the version identifier`_).
* After a final release, add a new empty section "Changes Since ..." in
HISTORY.txt.
* Update the web page (web/index.txt).
* Run docutils-update on the server.
* **Run alltests.py with svn version**
* **Send announcement email to:**
* docutils-develop@lists.sourceforge.net (also announcing the end of
the check-in freeze)
* docutils-users@lists.sourceforge.net
* doc-sig@python.org
* python-announce@python.org
* **Add a** `SourceForge News item`__, **with title "Docutils X.Y.Z released"**
__ https://sourceforge.net/p/docutils/news
**Mark as default download for all platforms.**
.. _wheels: https://packaging.python.org/en/latest/distributing.html#wheels
.. _pure Python wheels:
https://packaging.python.org/en/latest/distributing.html#pure-python-wheels
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End:
|
