====================
Making a ZSI Release
====================

The following instructions tell how to go about making a ZSI release.
The Makefile automates many of the more mechanical aspects of the
process.

The documentation is built using the same documentation tools used for
the standard Python documentation.  See `Documentation Tools`_ for
information on getting and setting up those tools.

1.  Announce your intent to make a release on the mailing list.  This
    gives folks a day or so to respond with info or last-minute
    checkins.

2.  Edit setup.cfg to set the version number in the ``[version]``
    section, if appropriate.  If you change the version number, set
    the ``release`` setting in the ``[bdist_rpm]`` section to 1.

3.  Make sure CHANGES is up to date, including the version number at
    the top.
    
4.  Make sure the documentation is up to date. Try all of the examples,
	and make sure they work. For a release candidate, the docs do not
	have to be up to date, but we must at least mark the parts of the
	docs that are no longer accurate. For a final release, the docs
	*must* be up to date with the code.

5.  Commit all changes to SVN.

6.  Run all the tests; they must all pass.  See `Running Tests`_ for
    details.

7.  Tag the SVN repository.  Release tags are of the form::

        "v" MAJOR "_" MINOR [ "_" PATCHLEVEL ] [ modifier serial ]

    where the optional segment containing PATCHLEVEL is included only
    if PATCHLEVEL is non-zero.  The modifier segment has only been
    used for release candidates (so far), for which the modifier is
    "RC" and the serial is the number of the candidate for this
    particular software version ("1", "2", etc.).

    You'll need to tag the ``wstools`` package separately, but using
    the same tag.

8.  Export the tagged sources from CVS.  You'll need to run the
    commands::

        cvs -d cvs.sourceforge.net:/cvsroot/pywebsvcs export -r TAG zsi
        cd zsi/ZSI/
        cvs -d cvs.sourceforge.net:/cvsroot/pywebsvcs export -r TAG wstools

9.  Build the release from the export.  Switch to the export directory
    (the one containing setup.py) and run **make kit**.

10.  Rename the PDF documentation.  If the patchlevel from setug.cfg is
    0, copy doc/zsi.pdf to dist/zsi-$MAJOR.$MINOR.pdf, otherwise copy
    it to dist/zsi-$MAJOR.$MINOR.$PATCHLEVEL.pdf.  This will leave you
    with all the files you need to upload in a single directory
    (dist/).

11. Using the constructed distribution (usually the .tar.gz version),
    build and test the software; they must all pass.  See `Running
    Tests`_ for details.

12. Use the SourceForge tools to create a release and upload the
    files.  If appropriate, hide obsolete releases.  Hiding old
    releases is normally only done if the older release contains
    security bugs or other critical bugs that render it unusable.

13. The web pages are in pywebsvcs.sourceforge.net, at the same level
    as the zsi directory.  Copy zsi.html from zsi/doc into there.
    Update index.html to refer (and link) to the new release.  Commit
    those changes.  The cron job will update it every couple of hours.

14. Announce the release:

    - Freshmeat.  The details of how to do this have been lost to the
      travesties of time, but there is a ZSI package there.

    - SourceForge.net news:  Create a news item in the project
      announcing the release.

    - Register the release with the Python Package Index (PyPI).  This
      can be done using **python setup.py register**.

    - comp.lang.python.announce


Documentation Tools
-------------------

The Python documentation tools include a script (**mkhowto**) that can
be used on any Unix or Cygwin installation that provides all the
required formatting tools.  The recommended way to use them is to
create a symbolic link to **mkhowto** from some directory on your
PATH.

The Python documentation tools can be acquired by any of these three
methods:

- Get a Python source release and unpack it.  Create the symlink to
  .../Python-VERSION/Doc/tools/mkhowto.

- Get the LaTeX version of the documentation package and unpack it.
  Create the symlink to .../Python-Doc-VERSION/tools/mkhowto.

- Get them from CVS.  If you have an existing Python checkout, you can
  symlink to the .../Doc/tools/mkhowto script in that.  If not, then
  you only need to check out the Doc/ tree::

    cvs -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/python \
        checkout -d someplace python/dist/src/Doc

  The symlink can then be made to .../someplace/tools/mkhowto.

If you want to skip the symlink, you can specify the MKHOWTO variable
when you run **make kit**::

  make MKHOWTO=.../Doc/tools/mkhowto kit

If you're working from unpacked Python sources or a complete Python
checkout, you can just point to that instead of typing the full path
to the **mkhowto** script::

  make PYSRCDIR=...


Running Tests
-------------

Before a release, all the tests must run to completion and pass.  This
entails running several scripts:

- test/test_zsi.py

- test/test_zsi_net.py

- test/wsdl2py/runTests.py

This is most easily done by setting the PYTHONPATH environment
variable to point to the directory containing the version of the ZSI
package that you want to test.

Before testing, build the software::

  python setup.py build

Set PYTHONPATH to point to the built package::

  PYTHONPATH=`pwd`/build/lib

The first two scripts can easily be run from any directory; once your
PYTHONPATH is set, just run the scripts::

  python test/test_zsi.py

  python test/test_zsi_net.py

The third script depends on a configuration file; see the
test/wsdl2py/README file for more information on running these tests.