=====================
KID RELEASE CHECKLIST
=====================

These notes describe the general procedure for releasing new version of Kid.


Pre-requisites
--------------

Make sure the following packages are installed on your system:

  * Python 2.3, Python 2.4 and Python 2.5
  * elementtree <http://effbot.org/zone/element-index.htm>
  * setuptools <http://peak.telecommunity.com/DevCenter/setuptools>
  * docutils <http://docutils.sourceforge.net>
  * buildutils <http://buildutils.lesscode.org>
  * pudge <http://pudge.lesscode.org>
  * py.test <http://codespeak.net/py/current/doc/test.html>

Most of the utility packages can be installed using ``easy_install``. For
``buildutils`` and ``pudge``, it's recommended that you grab the latest
revisions from subversion:

  $ easy_install http://lesscode.org/svn/pudge/trunk
  $ easy_install http://lesscode.org/svn/buildutils/trunk

Since some of the tests require py.test, this should be installed as well
(see http://codespeak.net/py/current/doc/getting-started.html).


Release Procedure
-----------------


1. Run Tests

  Check that all tests are passing:

    $ make test

  The tests are run for all Python versions 2.3, 2.4 and 2.5.

  I generally run tests on the following systems when possible:

    * Debian
    * SuSE Linux
    * Fedora Core 4
    * FreeBSD
    * Mac OS X / 10.4+
    * Windows XP (run the tests manually)

    If possible, run the TurboGears nosetests with the
    new Kid version to make sure nothing ha been broken.


2. Update the ez_setup.py script with the latest version
   from http://peak.telecommunity.com/dist/ez_setup.py


3. Bump version number in ``kid/release.py`` and ``doc/index.txt``,
    and ``kid.egg-info/PKG_INFO``. Also change download URL
    and possibly other meta data in ``kid.egg-info/PKG_INFO``.

4. Update build notes

   Update ``doc/notes.txt`` with release notes.


5. Commit / Tag

   After committing release related changes, make a note of the current
   changeset revision and then tag it:

     $ svn cp -m 'tagging [changeset] for VERSION release' \
                 svn://kid-templating.org/trunk \
                 svn://kid-templating.org/tags/VERSION


6. Build Distributables

   Make sure you have recent versions of setuptools and buildutils installed
   for Python 2.3, 2.4 and 2.5.

     $ pbu -i2.3,2.4,2.5 sdist bdist_egg

   You should now have ``dist/kid-VERSION.tar.gz``,
   ``dist/kid-VERSION-py2.3.egg``, ``dist/kid-VERSION-py2.4.egg``
   and ``dist/kid-VERSION-py2.5.egg``.
   This is generally all I release.

   I like to scan the file contents just to make sure nothing funny made its
   way into the dist process:

     $ tar tzf dist/kid-VERSION.tar.gz | less
     $ ls -1 dist/kid-0.9-*.egg | xargs -n1 unzip -l | less

   Now it is time to push to the CheeseShop:

     $ pbu -i2.3,2.4,2.5 sdist bdist_egg upload


7. Generate Checksums

   This is important for package maintainers. Most package repositories hold
   the policy that upstream distributables MUST include checksums and many
   require checksums to be signed.

     $ pbu checksum --sign

   (Leave off the --sign option if you're not setup with GPG.)

   This generates a `dist/kid-VERSION.sha` file and a
   `dist/kid-VERSION.sha.asc` file if the checksums are signed.


8. Publish Distributables

   Copy the entire dist directory to kid-templating.org:

     $ scp -rp dist kid-templating.org:/srv/kid-templating.org/www/htdocs/dist/VERSION

   Any release (major, minor, build, nightly) should have its own
   directory. Don't copy new distributables into existing dist
   directories. i.e., VERSION may be 0.9, 0.9a1, 0.9.5, 20060101, etc...

   Check that the files made it up properly and are accessible via HTTP:

     $ links http://www.kid-templating.org/dist/VERSION/

   or perhaps:

     $ curl http://www.kid-templating.org/dist/VERSION/kid-VERSION.sha

   NOTE: This process was automated through ``pbu`` at one point but I
   can't seem to get it working properly. I'll get it figured out and
   update this doc accordingly.


9. Build documentation

   Build the docs using buildutils/pudge:

     $ pbu pudge

   Files generated by pudge are placed under the ``doc/html`` directory.


10. Publish Docs

   Transfer the files generated under ``doc/html`` to kid-templating.org:

     $ scp -r doc/*.txt doc/html/* kid-templating.org:/srv/kid-templating.org/www/htdocs/

    Check and update the wiki pages at http://www.kid-templating.org/trac/wiki/,
    particularly make sure that this page is up to date:

    http://www.kid-templating.org/trac/wiki/GettingStarted