Distributing Gerald

Introduction

This document describes all of the steps to be followed when packaging and releasing a version of gerald.

Checking the Code

In a working copy (checked out from Subversion) first run pychecker:

$ pychecker gerald/*.py

Then when you have fixed all of the errors and looked at each of the warnings we bring out pylint:

$ pylint gerald

For pylint we need to make sure that we use the appropriate configuration file. The only change from the standard I’ve made to mine is to add the following line:

disable-msg=W0403,R0903,W0621

Tidying the Code

Set Logging Level

When developing I set the logging level to ‘DEBUG’, before distribution set this to ‘WARNING’. Open schema.py and comment out the line that says:

LOG = get_log('gerald', LOG_FILENAME, 'WARNING')

Make sure that any other line starting LOG = is commented out.

Set Version Number

At the moment each module has a __version__ attribute. This is probably confusing and should be changed. Until this is tidied up make sure every module has the same value in this attribute as the __init__.py module. Hopefully this will be the release number.

Make sure, before you package gerald that you set the version number in setup.py. This used to import the version number from the main gerald package but the statements that are executed on import of gerald cause easy_install to abort the installation.

Update the Documentation

Generating the Documentation

This project uses Sphinx for documentation. You will need to have it installed before generating the documentation.

First review and update each of the .rst files in the docs directory. Then in a working copy of the source code cd to the docs directory and simply type:

$ make html

This will generate the project documentation in html format in the docs/_build/html directory. Copy that directory to the project web site:

$ scp -r docs/_build/html andy47@scandium.sabren.com:/home/andy47/web/halfcooked.com/code/gerald/

Creating a PDF version of the documentation (with the appropriate modules installed) is as easy as typing:

$ make pdf

Releasing the Code

Tag the Release

First we need to complete all of the prior steps. Then we ‘tag’ the release.:

$ svn copy http://halfcooked.svn.sourceforge.net/svnroot/halfcooked/trunk http://halfcooked.svn.sourceforge.net/svnroot/halfcooked/tags/release-<revision number>

Or checkout the whole Subversion repository and then do the copy internally.:

$ svn checkout https://halfcooked.svn.sourceforge.net/svnroot/halfcooked/ hc-root
$ cd hc-root
$ svn copy trunk/ tags/release-<release number>

Packaging the Code

To send it to PyPI:

$ python setup.py sdist [ --formats=zip,gztar ] bdist_egg upload
$ python2.5 setup.py bdist_egg upload

Or to create local copies of the source distribution files:

$ python setup.py sdist --formats=zip,gztar

To create a .tar.gz and a .zip file.

Upload the Code to SourceForge

Upload the distribution files to SourceForge using their web interface. Log on to the project site at https://sourceforge.net/projects/halfcooked and navigate to the File Manager (Project Admin|File Manager)

Create a new folder under gerald named for the release. Right click it and select Uploads here and then upload the source and egg files using the Upload file link.

Update PyPi

Send a notification to PYPI of the latest release. In the release directory:

$ python setup.py register

Increment the version number

Now that the release is complete we can start work on the next version of the code. In the trunk, edit the __init__.py file in the gerald module and increment the __version__ variable appropriately.

---

Author:Andy Todd Last Updated:Tuesday the 8th of June, 2010.