Releasing
=========

:Contact: grubert@users.sourceforge.net, docutils-develop@users.sourceforge.net
:Revision: $Revision$
:Date: $Date$
:Copyright: This document has been placed in the public domain.

Notes on what happend while releasing.

CAUTION (2019-07-22)
====================

  While releasing 0.15 ::

    python3 setup.py sdist bdist_wheel
    python2 setup.py bdist_wheel

  This will result in the py2 wheel being identical to the py3 one.

  The name ``docutils-0.15-py2-none-any.whl`` cannot be used twice on pypi,
  build the py2-wheel and rename it ``docutils-0.15.post1-py2-none-any.whl``.
  (No code was changed therefore only filename change.)

  Name it ``docutils-0.15-post1-py2-none-any.whl`` then the version in the filename
  corresponds to the directory names in the wheel file.

  Maybe change the the version number in setup.py ?

Release 0.15 (2019-07-24)
=========================

branches/rel-0.15

Release 0.15.2 (2019-07-30)
===========================

Bump the version number to ease tool live.

Bump version ::

  set_version 0.15.2 
  python2 test/alltests.py
  python3 setup.py test3/alltests.py
  # visual inspection
  svn di | grep '^[+-]' | less -p '0.15.[12]'
  svn ci

Build py2 release upload to test.pypi ::

  mkdir py2 ; cd py2
  svn export svn+ssh://grubert@svn.code.sf.net/p/docutils/code/branches/rel-0.15/docutils
  cd docutils
  python2 setup.py sdist bdist_wheel
  python3 -m twine upload --repository-url https://test.pypi.org/legacy/ dist/docutils-0.15.2-py2-none-any.whl

Test in virtualenv ::

  virtualenv du2 ; cd du2
  export PYTHONPATH= ; . bin/activate

  python -m pip install --index-url https://test.pypi.org/simple/ --no-deps docutils
  cp -r ~/projects/docutils-rel-0.15/docutils/py2/docutils/test .
  python2 test/alltests.py
  # IGNORE stylesheet path differences  
  
  deactivate ; cd .. ; rm -rf du2

release to pypi from the exported source directory   ::

  python3 -m twine upload  dist/docutils-0.15.2*  

Test in new virtualenv ::

  virtualenv du2 ; cd du2
  export PYTHONPATH= ; . bin/activate

  pip install docutils
  # Successfully installed docutils-0.15.2

  cp -r ~/projects/docutils-rel-0.15/docutils/py2/docutils/test .
  python2 test/alltests.py
  # IGNORE stylesheet path differences  

  deactivate ; cd .. ; rm -rf du2

Build py3 release upload to test.pypi.
In the export/docutils ::

  # py3 and source 
  python3 setup.py bdist_wheel
  python3 -m twine upload --repository-url https://test.pypi.org/legacy/ dist/docutils-0.15.2-py3-none-any.whl

Test in virtualenv ::

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

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

BUG install 0.15 source. Check test.pypi web interface ... py3-wheel is there.
Retry::

  # Successfully installed docutils-0.15.2
  cp -r ~/projects/docutils-rel-0.15/docutils/py2/docutils/test3 .
  python test3/alltests.py
  # IGNORE upper directory Failure
  
  deactivate ; cd .. ; rm -rf du3 

release to pypi from the exported source directory   ::

  python3 -m twine upload  dist/docutils-0.15.2-py3*  

Wait for wheel to appear on pypi.org.

Test in virtualenv ::

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

  pip install docutils
  # Successfully installed docutils-0.15.2
  
  cp -r ~/projects/docutils-rel-0.15/docutils/py2/docutils/test3 .
  python test3/alltests.py
  # IGNORE upper directory Failure

  deactivate ; cd .. ; rm -rf du3

FINE 0.15.2

Release 0.15.1 (2019-07-24)
===========================

Bug fix release for python2 only.

* set version 0.15.1
* ``python2 setup.py sdist bdist_wheel``
* ``python3 -m twine upload --repository-url https://test.pypi.org/legacy/ dist/docutils-0.15.1-py2-none-any.whl ``
* in a new virtualenv::

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

  and then test/alltests.py 
* ``python3 -m twine upload  dist/docutils-0.15.1*``

  upload py2-wheel and source.
* in a new virtualenv::

    python -m pip install docutils

  and then test/alltests.py 

* (2019-07-25) replace source by -post1

  Name it ``docutils-0.15.1-post1.tar.gz`` to make sure

  * It is unchanged library code: *post1*
  * the version is still 0.15.1: therefore separate with ``-``

  * run the tests somewhere, fix and commit.
    Then::

      svn export svn+ssh://@svn.code.sf.net/p/docutils/code/branches/rel-0.15/docutils d
      cd d
      python2 setup.py sdist
    
  * check ``tar tzf dist/docutils-0.15.1.tar.gz`` for remaining files.
    Then::

      mv dist/docutils-0.15.1.tar.gz dist/docutils-0.15.1-post1.tar.gz
      python -m twine upload dist/docutils-0.15.1-post1.tar.gz

  * Build a venv (python3), install docutils, copy test3 from development
    directory and run the test.

    As there is no 0.15.1 wheel for python3 this will be the source package. 
Release 0.15
============

svn revision: 8258 - start of release

* test on linux 2.7 3.7 : passed
* test on macosx python2.6: 

  - 7 failures due to different error messages. see below
  - 4 errors: python2.6 sys.version_info is a tuple no dictionary 
    FIXED: revision 8260

* test on macosx 2.7 3.4 3.6 3.7 : passed
* change version to : 0.15rc1.dev

  - run tests: python 2.7 and 3.7

* extract changes from HISTORY.txt to RELEASE-NOTES.txt
* rename headings in HISTORY.txt and RELEASE-NOTES.txt
* run release.sh stage 2: do a clean checkout and packing
* run local test with python 2.6 2.7 3.4 3.6 3.7
* upload to sourceforge.net. Keep 0.15 as latest, stable.
* Fix: README.txt version number BY HAND
* pypi :

  - docutils is registered
  - check setup.py : add classifier 'Programming Language :: Python :: 3.7'
  - Login to pypi (see https://packaging.python.org/tutorials/packaging-projects/)

    - python3 -m pip install --user --upgrade setuptools wheel

      (warns about not being in PATH. symlink into my/bin)
    - python3 setup.py sdist bdist_wheel ::

        /Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/distutils/dist.py:274: UserWarning: Unknown distribution option: 'python_requires'
          warnings.warn(msg)

        error: invalid command 'bdist_wheel'

    - add import setuptools to setup.py
    - python3 setup.py sdist bdist_wheel
    - python2 setup.py bdist_wheel
    - python3 -m pip install --user --upgrade twine
    - twine upload dist/*

  check on pypi: 0.15 is there.

* update website docs

  - in directory web edit index.txt
  - in sandbox/infrastructure run ./docutils-update.local

* set version of repository to 0.16b.dev


Release 0.14
============

svn revision: 8145 - start of release - 0.15.0 beta

Prerelease 0.14a0
=================

svn revision: 8082 Prerelease 0.14a0
svn revision: 8078 Prerelease 0.14.0a

* merge changes from HISTORY.txt to RELEASE-NOTES.txt
* extract release number description setting from release.sh
* rename headings in HISTORY.txt and RELEASE-NOTES.txt
* run release.sh stage 2: do a clean checkout and packing
* run local test with python2.7
* upload to sourceforge.net. Keep 0.13 as latest, stable.
* reister on to pypi and upload tgz
* pypi: unset hide old releases


Release 0.13
============

svn revision: 7980

Tests
-----

Tests are run from svn checkout, only few from install.

* windows7 python 2.7.5: OK

* windows7 python 3.4.1: as in previous release

  * test.css path error (filed #256) 
  * test_parsers\test_rst\test_directives\test_include.py::

* macosx 10.10 python 2.7.10: OK
* macosx 10.10 python 3.3.2: OK
* macosx 10.10 python 3.4.1: OK

* ubuntu 12.04 python 2.7.3: OK
* ubuntu 12.04 python 3.2.3: OK

* testing tarball 0.13.1 (build sdist) ::

    +++ functional/output/standalone_rst_html5.html
    @@ -7,9 +7,9 @@
     <meta content="A test document, containing at least one example of each reStructuredText construct." lang="en" name="description" xml:lang="en" />
    -<link rel="stylesheet" href="../input/data/minimal.css" type="text/css" />
    -<link rel="stylesheet" href="../input/data/plain.css" type="text/css" />
    -<link rel="stylesheet" href="../input/data/math.css" type="text/css" />
    +<link rel="stylesheet" href="../../minimal.css" type="text/css" />
    +<link rel="stylesheet" href="../../plain.css" type="text/css" />
    +<link rel="stylesheet" href="../../math.css" type="text/css" />
     </head>

  this is because ``test/functional/input/data/minimal.css`` is a symlink to
  ``../../../../docutils/writers/html5_polyglot/minimal.css`` and release_test.sh 
  removes directory docutils to ensure the test uses the installed docutils
  not the unzipped.

  FIX: remove docutils/__init__.py

Release 0.12
============

svn revision: 7749

Tests
-----

Tests are run from svn checkout, only few from install.

Python3 tests are run ::

  rm -rf build test3
  python3 setup.py build
  PYTHONPATH=build/lib python3 test3/alltests.py

* ubuntu 8.04: python 2.4.5, 2.5.2, 2.6.7, 2.7.2 OK

  python 2.6.4rc1 6 failure due to change in error message: no such file ...  

  python 3.2.3 OK

* macosx 10.6.8: python 2.5.4, 2.7.3

  python 2.6.1 6 failure due to change in error message: no such file ...  

  python 3.2, 3.4.1 OK

* ubuntu 14.04: pyton 2.7.6,  python 3.4.0 OK

* windows7: python 2.7.5 

  Error (filed #256): test_writers/test_html4css1_template.py::

      stylesheet = """\
    - <link rel="stylesheet" href="/test.css" type="text/css" />"""
    + <link rel="stylesheet" href="C:/test.css" type="text/css" />"""
    ?                              ++

  python 3.4.1

  * test.css path error (filed #256) 
  * test_parsers\test_rst\test_directives\test_include.py::

      b'Encoding:\n\n.. include:: test_parsers/test_rst/test_directives/utf-16.csv\n   :encoding: utf-16\n'
        File "test3\alltests.py", line 40, in write
          string = string.encode('raw_unicode_escape').decode('ascii')
      UnicodeDecodeError: 'ascii' codec can't decode byte 0xb0 in position 994: ordinal not in range(128)

   fiddling with alltests.py (uncommitted) ::

      <system_message level="4" line="1" source="test data" type="SEVERE">
        <paragraph>
            Problem with "raw" directive:
            UnicodeDecodeError: \'utf-16-be\' codec can\'t decode bytes in position 90-91: illegal encoding
        <literal_block xml:space="preserve">
            .. raw:: html
               :file: test_parsers/test_rst/test_directives/utf-16.csv
               :encoding: utf-16''' != '''\



Release 0.11
============

Summary
-------

``sandbox/infrastructure/release.sh`` tries running ``test/alltests.py`` after 
installing the new release, this fails because

* tests depends on e.g. ``../docs/user/rst/images/title.png`` or ``../HISTORY.txt``, 
  but thess are neither in the test directory tree nor in the installed software. 

* there is a lot of code trying to handle varying installation targets ``/usr/lib``
  ``/usr/local/lib` and not yet ``/usr/lib/pymodules``.

Change testing to:

1. build and install
2. extract docutils-<release>.tar.gz into tmp
3. remove docutils/docutils directory, just to make shure it is not used.
4. run test/alltest.py in this directory, so all files are where they are
   while development.

Following failure becuase docutils-library directory was removed, therefore 
docutils/writers/html4css1/html4css1.css is not found::

  ======================================================================
  FAIL: test_custom_stylesheet_dir (test_writers.test_html4css1_misc.SettingsTestCase)
  ----------------------------------------------------------------------
  Traceback (most recent call last):
    File "/... 0.11/test/test_writers/test_html4css1_misc.py", line 81, in test_custom_stylesheet_dir
      self.assertIn('docutils/writers/html4css1/html4css1.css', styles)
    File "/... 0.11/test/DocutilsTestSupport.py", line 138, in assertIn
      msg or '%s not in %s' % _format_str(a, b))
  AssertionError: 'docutils/writers/html4css1/html4css1.css' not in u'''\
  <link rel="stylesheet" href="html4css1.css" type="text/css" />
  <link rel="stylesheet" href="data/ham.css" type="text/css" />
  '''


Tests
-----

* ubuntu 8.04 2.4.5, 2.5.2, 2.6.7, 2.7.2 OK

  python 2.6.4rc1 6 failure due to change in error message: no such file ...  

  Python 3.2.3 : OK (roman.py left over from last release)

* macosx 10.6.8: python 2.5.4, 2.7.3

  python 2.6.1 6 failure due to change in error message: no such file ...  

  python 3.2: roman.py for py3 required.

Release.sh
----------

release.sh does not work on MacOSX.

installation on ubuntu 10.04 breaks test script::

  Working directory: /usr/local/lib/python2.6/site-packages/docutils-test
  Docutils package: /usr/local/lib/python2.6/dist-packages/docutils

  ======================================================================
  FAIL: test_find_file_in_dirs (test_utils.HelperFunctionsTests)
  ----------------------------------------------------------------------
  Traceback (most recent call last):
    File "/usr/local/lib/python2.6/site-packages/docutils-test/test_utils.py", line 295, in test_find_file_in_dirs
      '../HISTORY.txt')
  AssertionError: 'HISTORY.txt' != '../HISTORY.txt'

Stopping for now.



Release 0.10
============

* same failures for some python2.6 versions ::

              Problems with "raw" directive path:
       -      InputError: [Errno 2] No such file or directory: 'non-existent.file'.
       +      InputError: (2, 'No such file or directory').

* testing release tarball ::

    ======================================================================
    FAIL: test_dependencies (__main__.RecordDependenciesTests)
    ----------------------------------------------------------------------
    Traceback (most recent call last):
      File "docutils-test/test_dependencies.py", line 61, in test_dependencies
        self.assertEqual(record, expected)
    AssertionError: [u'data/include.txt', u'data/raw.txt'] != [u'../docs/user/rst/images/title.png',
    u'data/include.txt', u'data/raw.txt']
    
    ...

  because ../docs is not there if run from /usr/../pythonx.x/site-packages/docutils-test.

Release 0.9.1
=============

same failures as for 0.9 plus

* python 2.3: twice, ignored ::

  -             [Errno 2] No such file or directory: 'bogus.csv'.
  +             [Errno 2] No such file or directory: u'bogus.csv'.

  python 2.3 ::

    ======================================================================
    ERROR: test_unicode (test_error_reporting.ErrorStringTests)
    ----------------------------------------------------------------------
    Traceback (most recent call last):
      File "/usr/local/lib/python2.3/site-packages/docutils-test/test_error_reporting.py", line 153, in test_unicode
        self.assertEqual(u'ImportError: %s' % SafeString(self.bs),
    UnicodeDecodeError: 'ascii' codec can't decode byte 0xfc in position 0: ordinal not in range(128)

Note: sf takes some considerable time till the downlods are visible for normal users.
  More than 1 hour , the folder files/docutils/0.9.1 exists and the webinterface
  correctly summarizes "Totals: 2 Items	 	1.6 MB" but nothing is shown.

Release 0.9
===========

* python 2.3 unittest.TestCase has no assertTrue
* python 2.3 keyword dictionaries update method does not support kwargs

Ignored test errors

* python 2.3: unicode problems. 2.3 support is likely to be ended soon.
  Systems with only 2.3 might not even know of unicode.

* PIL ``AttributeError: 'module' object has no attribute 'Image'``

  A problem in PIL ? 
  Tested and failiing on

  - ubuntu8.04, python 2.4, 2.5  
  - ubuntu10.04, python 2.6  
  - ubuntu11.10, python 2.7  

* python 2.6.4rc1 has a different error message format::

              Problems with "raw" directive path:
       -      InputError: [Errno 2] No such file or directory: 'non-existent.file'.
       +      InputError: (2, 'No such file or directory').

  but not in python 2.6.7
