/usr/share/doc/docutils-doc/docs/dev/release.html is in docutils-doc 0.14+dfsg-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 | <?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.14: http://docutils.sourceforge.net/" />
<title>Docutils Release Procedure</title>
<meta name="authors" content="David Goodger Lea Wiemann open to all Docutils developers" />
<meta name="date" content="2017-08-03" />
<meta name="copyright" content="This document has been placed in the public domain." />
<link rel="stylesheet" href="../../css/html4css1.css" type="text/css" />
</head>
<body>
<div class="document" id="docutils-release-procedure">
<h1 class="title"><a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> Release Procedure</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Authors:</th>
<td>David Goodger
<br />Lea Wiemann
<br />open to all Docutils developers</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference external" href="mailto:docutils-develop@lists.sourceforge.net">docutils-develop@lists.sourceforge.net</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2017-08-03</td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>8146</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>This document has been placed in the public domain.</td></tr>
</tbody>
</table>
<div class="section" id="assumptions-and-their-failure">
<h1>Assumptions and their failure</h1>
<p>On the test machine python2.4, 2.5, 2.6, 2.7 and 3.2, 3.3, and 3.4
are installed.
Some in /usr/ some under /usr/local.</p>
<p>Assumption: If python2.6 is in /usr/bin/ then site-packages is under
/usr/local/lib/python2.6.</p>
<p>On new ubuntu 12.10</p>
<ul>
<li><p class="first">python2.7 is here /usr/bin/python2.7.</p>
</li>
<li><p class="first">in /usr/lib are python2.7, pymodules and pyshared.</p>
<p>in /usr/lib/python2.7 no site-packages directory even after installation
of docutils</p>
<p>in /usr/local/lib/python2.7 are dist-packages site-packages.</p>
<p>site-packages is empty.</p>
<p>docutils is installed under dist-packages.</p>
<p>pymodules has a python2.7 directory.</p>
</li>
</ul>
</div>
<div class="section" id="releasing">
<h1>Releasing</h1>
<div class="section" id="version-numbers">
<h2>Version numbers</h2>
<p>Version numbers shall follow the <a class="reference external" href="policies.html#version-numbers">Docutils Project Policies</a> and comply
with <a class="reference external" href="https://www.python.org/dev/peps/pep-0440/">PEP 440</a>.</p>
<p>Especially, mark pre-releases and the repository version/snapshots as
"between" releases (cf. <a class="reference external" href="https://sourceforge.net/p/docutils/feature-requests/50/">Feature Request #50</a> and the discussion on
docutils-devel on May 28 2017), e.g.</p>
<div class="line-block">
<div class="line-block">
<div class="line">prev. release 0.13.1,</div>
<div class="line">prerelease 0.14rc1,</div>
</div>
<div class="line">[prereleases 0.14rc2, ...]</div>
<div class="line-block">
<div class="line">release 0.14,</div>
<div class="line">repo/snapshots 0.15.dev</div>
</div>
<div class="line">[bugfix relases 0.14.1, ...] # branches off of the 0.14 release.</div>
</div>
<p>The repository version number is always equal to the last released
version + 1, with a .dev suffix: <tt class="docutils literal"><span class="pre"><major>.<minor+1>.dev</span></tt>.
(Exception: during "feature freeze" between pre-release and release it may
point to the next pre-release.)</p>
</div>
<div class="section" id="release-steps">
<h2>Release steps</h2>
<p>REWORK FOR SOURCEFORGE REPO</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Steps in boldface text are <em>not</em> covered by the release script
at sandbox/infrastructure/release.sh. "Not covered" means that you
aren't even reminded of them.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This document does not cover branching and tagging, but the
release script does.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You may want to use <a class="reference external" href="http://releaseforge.sourceforge.net/">ReleaseForge</a> instead of using
SourceForge's file release system.</p>
</div>
<ul>
<li><p class="first"><strong>On the Docutils-develop mailing list, announce that the release is
going to be made, update the release notes and ask for additions.</strong></p>
<p><strong>Announce the date of the feature freeze, at least a week away.</strong></p>
<p>Consult HISTORY.TXT for changes.</p>
</li>
<li><p class="first"><strong>Announce a check-in freeze on Docutils-develop.</strong></p>
</li>
<li><p class="first"><strong>Announce the upcoming release at the Sphinx-devel mailing list
and ask for testing with Sphinx.</strong>
(This step can be skipped for bugfix releases.)</p>
</li>
<li><p class="first">update <a class="reference internal" href="#version-numbers">version numbers</a>:</p>
<p>We want pre-release tags <tt class="docutils literal">rcN</tt> for pre-releases, development release tag
<tt class="docutils literal">.dev</tt> for snapshots and installs from the repository.</p>
<p>For a prerelease</p>
<ol class="arabic simple" start="0">
<li>before release <tt class="docutils literal"><span class="pre"><next-release-number>.dev</span></tt></li>
<li>set this to <tt class="docutils literal"><span class="pre"><next-release-number>.rc1</span></tt></li>
<li>release</li>
<li>increase prerelease number in the repository</li>
</ol>
<p>For a release</p>
<ol class="arabic simple" start="0">
<li>before release <tt class="docutils literal"><span class="pre"><next-release-number>.dev</span></tt> or
<tt class="docutils literal"><span class="pre"><next-release-number>.rc<N></span></tt></li>
<li>set this to <tt class="docutils literal"><span class="pre"><next-release-number></span></tt> without prerelease character.</li>
<li>release</li>
<li>set to <tt class="docutils literal"><span class="pre"><major>.<minor+1>.dev</span></tt> in the repository (trunk).</li>
</ol>
<p>see what <tt class="docutils literal">sandbox/infrastructure/release.sh</tt> can aid</p>
<p>Call <tt class="docutils literal">sandbox/infrastructure/set_release.sh new_version</tt>.
For details see the script.</p>
<p><tt class="docutils literal">new_version</tt> is major.minor[.micro][<pre>][.dev]</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><em>BUG</em> test tarball requires root password, but it is possible to
skip this stage interactively, and testing should be done before
release.</p>
</div>
</li>
<li><p class="first">Change <tt class="docutils literal">__version_details__</tt> in docutils/docutils/__init__.py to
"release" (from "repository").</p>
</li>
<li><p class="first">Check the <span class="target" id="version-number">version number</span> in the following files, should be already
correct:</p>
<ul class="simple">
<li>docutils/setup.py</li>
<li>docutils/docutils/__init__.py</li>
<li>docutils/test/functional/expected/* ("Generator: Docutils X.Y[.Z]")</li>
<li>docutils/README.txt</li>
<li>web/index.txt</li>
</ul>
</li>
<li><p class="first">Close the "Changes Since ..." section in docutils/HISTORY.txt.</p>
</li>
<li><p class="first">Clear/unset the PYTHONPATH environment variable.</p>
</li>
<li><p class="first">Create the release tarball:</p>
<ol class="loweralpha">
<li><p class="first">Create a new empty directory and <tt class="docutils literal">cd</tt> into it.</p>
</li>
<li><p class="first">Get a clean snapshot of the main tree:</p>
<pre class="literal-block">
svn export svn://svn.code.sf.net/p/docutils/code/trunk/docutils
</pre>
<p>or via the [Download Snapshot] button at
<a class="reference external" href="http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/">http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/</a></p>
</li>
<li><p class="first">Use Distutils to create the release tarball:</p>
<pre class="literal-block">
cd docutils
python setup.py sdist
</pre>
</li>
</ol>
</li>
<li><p class="first">Expand and <span class="target" id="install">install</span> the release tarball in isolation:</p>
<ol class="loweralpha">
<li><p class="first">Expand the tarball in a new location, not over any existing
files.</p>
</li>
<li><p class="first">Remove the old installation from site-packages (including
roman.py, and optparse.py, textwrap.py).</p>
<p>"remove" might fail, see <span class="target" id="id1">Assumptions and their failure</span></p>
<p>Install from expanded directory:</p>
<pre class="literal-block">
cd docutils-X.Y.Z
python setup.py install
</pre>
<p>The "install" command may require root permissions.</p>
</li>
<li><p class="first">Repeat step b) for all supported Python versions.</p>
</li>
</ol>
</li>
<li><p class="first">Run the <span class="target" id="test-suite">test suite</span> from the expanded archive directory with all
supported Python versions on all available platforms (GNU/Linux, Mac
OS X, Windows):</p>
<pre class="literal-block">
cd test ; python -u alltests.py
</pre>
</li>
<li><p class="first">Add a directory X.Y.Z (where X.Y.Z is the current version number
of Docutils) in the webroot (i.e. the <tt class="docutils literal">htdocs/</tt> directory).
Put all documentation files into it:</p>
<pre class="literal-block">
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:
</pre>
<p>Now log in to shell.sourceforge.net and:</p>
<pre class="literal-block">
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
</pre>
</li>
<li><p class="first">Upload the release tarball, release.sh tries with scp.</p>
</li>
<li><p class="first">Access the <span class="target" id="file-release-system">file release system</span> on SourceForge (Admin
interface).</p>
<p><tt class="docutils literal"><span class="pre">https://sourceforge.net/projects/docutils/files/docutils/</span></tt></p>
<ul class="simple">
<li>change into the released version's directory</li>
<li>click <tt class="docutils literal">(i)</tt> button of the tar.gz-file</li>
<li>select as default download for all operating systems.</li>
</ul>
</li>
<li><p class="first">Submit a notification on project news.</p>
</li>
<li><p class="first">For verifying the integrity of the release, download the release
tarball (you may need to wait up to 30 minutes), <a class="reference internal" href="#install">install</a> it, and
re-run the <a class="reference internal" href="#test-suite">test suite</a>.</p>
</li>
<li><p class="first">Register with PyPI (<tt class="docutils literal">python setup.py register</tt>).</p>
<p>Set the download-url so eggs can access older releases.</p>
</li>
<li><p class="first">Restore <tt class="docutils literal">__version_details__</tt> in docutils/docutils/__init__.py to
"repository" (from "release").</p>
</li>
<li><p class="first">Bump the <a class="reference internal" href="#version-number">version number</a> again.</p>
</li>
<li><p class="first">Add a new empty section "Changes Since ..." in HISTORY.txt.</p>
</li>
<li><p class="first">Update the web page (web/index.txt).</p>
</li>
<li><p class="first">Run docutils-update on the server.</p>
</li>
<li><p class="first"><strong>Run alltests.py with svn version</strong></p>
</li>
<li><p class="first"><strong>build wheels</strong>:</p>
<pre class="literal-block">
pip wheel docutils
pip3 wheel docutils
</pre>
<p>This builds <a class="reference external" href="https://packaging.python.org/en/latest/distributing.html#wheels">wheels</a> (<a class="reference external" href="https://packaging.python.org/en/latest/distributing.html#pure-python-wheels">pure Python wheels</a> for Python 2 and 3
respectively) by downloading the new release from pypi.</p>
<p><a class="reference external" href="https://packaging.python.org/en/latest/distributing.html#upload-your-distributions">Upload the wheels to PyPI</a>.</p>
<dl class="docutils">
<dt>Question:</dt>
<dd><p class="first">Can we have an tar.gz (distutil) and a py2-wheel and a py3-wheel
on pypi and will installers select the correct files?</p>
<p class="last">2017-06-09 it seems to according to experience with 0.13.1.</p>
</dd>
</dl>
</li>
<li><p class="first"><strong>Send announcement email to:</strong></p>
<ul class="simple">
<li><a class="reference external" href="mailto:docutils-develop@lists.sourceforge.net">docutils-develop@lists.sourceforge.net</a> (also announcing the end of
the check-in freeze)</li>
<li><a class="reference external" href="mailto:docutils-users@lists.sourceforge.net">docutils-users@lists.sourceforge.net</a></li>
<li><a class="reference external" href="mailto:doc-sig@python.org">doc-sig@python.org</a></li>
<li><a class="reference external" href="mailto:python-announce@python.org">python-announce@python.org</a></li>
</ul>
</li>
<li><p class="first"><strong>Add a `SourceForge News item`__, with title "Docutils X.Y.Z released"</strong></p>
<p><strong>Mark as default download for all platforms.</strong></p>
</li>
<li><p class="first"><strong>Register with freecode.</strong> Add a new release for the
<a href="#id4"><span class="problematic" id="id5">`Docutils project`__</span></a>. (freecode is freshmeat.net's new name)</p>
</li>
</ul>
<!-- Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End: -->
</div>
</div>
<div class="system-messages section">
<h1>Docutils System Messages</h1>
<div class="system-message" id="id4">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">docs/dev/release.txt</tt>); <em><a href="#id5">backlink</a></em></p>
Anonymous hyperlink mismatch: 1 references but 2 targets.
See "backrefs" attribute for IDs.</div>
</div>
</div>
</body>
</html>
|