.. include:: ../header.txt

=============================
 Docutils_ Release Procedure
=============================

:Authors: David Goodger; Lea Wiemann; open to all Docutils developers
:Contact: docutils-develop@lists.sourceforge.net
:Date: $Date: 2023-05-11 16:23:48 +0200 (Do, 11. Mai 2023) $
:Revision: $Revision: 9382 $
: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** .

* Update RELEASE-NOTES.txt add section ``Release <version>``.

  Consult HISTORY.txt for important changes.

* Change HISTORY.txt title ``Changes Since <previous release>`` to ``Release <version>``.

* Set new version (replace ``<version>`` with the new version indentifier
  and ``<docutils-repository-root>`` with the dir containing
  ``HISTORY.txt`` and ``RELEASE-NOTES.txt``)::

      cd <docutils-repository-root>
      ../sandbox/infrastructure/set_version.sh <version>

  Check what was changed by ``set_version.sh``.

  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::

    python3 setup.py sdist
    python3 setup.py bdist_wheel

* check sdist for html-files in docutils.egg-info.
* Upload wheel and source to test.pypi::

    python3 -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*

  Test in venv. NOTE use --pre for prereleases::

    python3 -m venv du3 ; cd du3
    export PYTHONPATH= ; . bin/activate

    python -m pip install --index-url https://test.pypi.org/simple/ --no-deps docutils

    cp -Lr ../docutils-code/docutils/test .
    python test/alltests.py

    python -m pip uninstall docutils
    deactivate ; cd .. ; rm -r du3

* Commit changes ... the changed version number.

* 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 ::

    python3 setup.py sdist
    python3 setup.py bdist_wheel

* Now upload to pypi::

    python3 -m twine upload  dist/docutils-#.#*

* Remove previous package from local cache::

    find .cache/pip/wheels -name docutils\*whl -exec rm -v -i {} \;

* and test::

    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.

* 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 {} \;
    rm -r docutils.egg-info
    rsync -e ssh -r -t ./ web.sourceforge.net:/home/project-web/docutils/htdocs/#.#

* Check web/index.txt 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
* test with py3
* docutils/HISTORY.txt: add title "Changes Since #.#"
* run sandbox/infrastructure/docutils-update.local


..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   End: