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
|
.. include:: ../header.rst
=============================
Docutils_ Release Procedure
=============================
:Authors: David Goodger; Lea Wiemann; open to all Docutils developers
:Contact: docutils-develop@lists.sourceforge.net
:Date: $Date: 2025-06-10 22:41:26 +0200 (Di, 10. Jun 2025) $
:Revision: $Revision: 10164 $
:Copyright: This document has been placed in the public domain.
.. _Docutils: https://docutils.sourceforge.io/
Steps to take and watch
-----------------------
Make a clean checkout of svn.code.sf.net/p/docutils/code/trunk/docutils
to avoid having development files in the released packages.
Test, package and release this checkout.
* Announce the upcoming release on docutils-develop list.
Consider **feature freeze** or/and **check-in freeze** .
* set_version.sh does not change HISTORY.rst and RELEASE-NOTES.rst.
Why ? Maybe because the underline of the section needs to be changed anyway
and personally I like to look around.
Maybe change this.
* Change HISTORY.rst title ``Release <version> (unublished)``:
Change the version insert date for unpublished.
* Update RELEASE-NOTES.rst section ``Release <version> (unpublished)``.
Change the version insert date for unpublished.
Consult HISTORY.rst for important changes.
* Set new version (replace ``<version>`` with the new version indentifier
and ``<docutils-repository-root>`` with the dir containing
``HISTORY.rst`` and ``RELEASE-NOTES.rst``)::
cd <docutils-repository-root>
../sandbox/infrastructure/set_version.sh <version>
Check what was changed by ``set_version.sh``.
Change acchordingly docutils/__init__.py ::
__version_info__ = VersionInfo(
major=0,
minor=21,
micro=0,
releaselevel='candidate', # one of 'alpha', 'beta', 'candidate', 'final'
serial=1, # pre-release number (0 for final releases and snapshots)
release=False # True for official releases and pre-releases
)
Run tests ::
export PYTHONWARNINGS=default
python3 test/alltests.py
or use tox.
In case of errors, clearing ``docutils/__pycache__`` may help.
``export PYTHONWARNINGS=default`` prints DeprecationWarnings in python3.
* Generate wheel and source-distribution, e.g.::
python3 -m pip install build
python3 -m build .
check file sizes: the 0.21.2 wheel was 574K the sdist 2,2M.
* Test the wheel in local environment
From checkout::
cd ..
python3 -m venv du3
cd du3
. bin/activate
pip install <checkout-dir>/dist/... .whl
# CAUTION copy test from modified not yet committed source tree.
cp -Lr ../docutils-code/docutils/test .
python test/alltests.py
Uploads to pypi/test.pypi can not be overwritten, require a new version.
* Commit changes ... the changed version number.
* build again and test locally.
* Upload wheel and source to test.pypi.
Set repository and key in ~/.pypirc with a <server-name> and
password token::
python3 -m twine upload --repository <server-name> dist/*
Change directory outside of checkout and test in venv.
NOTE use --pre for prereleases::
python3 -m venv du3 ; cd du3
export PYTHONPATH= ; . bin/activate
pip install --index-url https://test.pypi.org/simple/ --no-deps docutils
# CAUTION copy test from modified not yet committed source tree.
cp -Lr ../docutils-code/docutils/test .
python test/alltests.py
Ignore missing HISTORY.rst it is not in the wheel file.
if ok ::
deactivate ; cd .. ; rm -r du3
Test the sdist::
python3 -m venv du3s ; cd du3s
export PYTHONPATH= ; . bin/activate
pip install --index-url https://test.pypi.org/simple/ --no-binary docutils docutils
sdist installation fails with subprocess not finding flit_core .
test.pypi has flit 3.5.1 but installs 0.5 preinstalling flit_core did not work
either ... why.
postbone sdist test to pypi::
cp -Lr ../docutils-code/docutils/test .
python test/alltests.py
Ignore ``test_find_file_in_dirs`` fails because HISTORY.rst is missing or/and
missing pil.::
deactivate ; cd .. ; rm -r du3s
* If final release
- tag #.# (Note: only directory docutils is copied)::
svn copy svn+ssh://grubert@svn.code.sf.net/p/docutils/code/trunk/docutils \
svn+ssh://grubert@svn.code.sf.net/p/docutils/code/tags/docutils-#.# \
-m "tagging release #.#"
- Update your source directory.
- Rebuild wheel and source-distribution, e.g::
python3 -m build
* Upload to pypi::
python3 -m twine upload --repository <server-name> dist/docutils-#.#*
* Remove previous package from local cache::
find .cache/pip/wheels -name docutils\*whl -exec rm -v -i {} \;
* Test the sdist
::
python3 -m venv du3s ; cd du3s
export PYTHONPATH= ; . bin/activate
pip install --no-binary docutils docutils
cp -Lr ../docutils-code/docutils/test .
python test/alltests.py
Ignore ``test_find_file_in_dirs`` fails because HISTORY.rst is missing::
deactivate ; cd .. ; rm -r du3s
* and wheel::
python3 -m venv du3 ; cd du3
export PYTHONPATH= ; . bin/activate
pip install --no-deps docutils
cp -Lr ../docutils-code/docutils/test .
python test/alltests.py
deactivate ; cd .. ; rm -r du3
* Notify to docutils-developer and user.
For candidate releases change version to rc#+1dev.
* set_version #.rc#+1.dev
change docutils/__init__.py
test
* docutils/HISTORY.rst: add section "Release <version> (unpublished)"
* docutils/RELEASE-Notes.rst: add section "Release <version> (unpublished)"
* test again
* commit
* run sandbox/infrastructure/docutils-update.local
For final releases
* upload source and generated html to sf-htdocs/#.# ::
mkdir tmp1
cd tmp1
tar xzvf ../dist/docutils-#.#.tar.gz
cd docutils-#.#/
python3 tools/buildhtml.py .
find . -name \*.pyc -exec rm -v {} \;
find . -name __pycache__ -exec rmdir -v {} \;
rsync -e ssh -r -t ./ web.sourceforge.net:/home/project-web/docutils/htdocs/#.#
* Check web/index.rst for necessary corrections.
* Run sandbox/infrastructure/docutils-update.local to update web-content.
* Release to sourceforge.
- Upload docutils-#.#.tar.gz and release notes to sourceforge.
- Select docutils-#.#.tar.gz as default for all OS.
* set_version #.{#+1}b.dev
* docutils/HISTORY.rst: add title "Changes Since #.#"
* run sandbox/infrastructure/docutils-update.local
.. Emacs settings
Local Variables:
mode: indented-text
mode: rst
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End:
|