Table Of Contents

This Page


Some issues are tedious to deal with ona regular basis, for examples:

  • synchronizing the version in multiples files,
  • ensuring that all tests pass when releasing,
  • publishing the software module and documentation where the users expects them,

If handled correctly, the developer can focus on the features, it is more fun, and the users gets awesome softwares.


The sources are kept in a git repository on github (, because git is a powerful source configuration management that the author wishes to learn. Install the git commands on your system (sometimes packaged as git-core) and use the following to retrieve the sources:

git clone git://

The released software module is available on the Python package index and can be installed using easy_install or pip

Github also provides a handy way to publish the documentation on the web. The documentation sources are located in the doc/ source directory and are composed of restructured text pages built by the Sphinx documentation system. The output of Sphinx are nice static html pages which can be copied to the gh-pages special branch of the git repository. Github treats the branch specially by serving this branch through the web at this url:

There is an issue tracker at

There is also a wiki automatically set up by github, but the author has a personal preference for using a good text editor on files than typing characters in a web form.


Whenever the code changes, the version gets incremented. The version number is based on the concpet of public interfaces and backward compatibility. For this project, the version number is composed of three numbers: major.minor.patch

  1. if the changes are seamless for the user, then the patch gets incremented. Usually, internal refactoring or backward compatible bugfixes cause a bump in the patch number,
  2. if the user has access to new features, if the changes are substantial and backward compatible, the minor number gets incremented.
  3. the major number is incremented when the user will have to change the way it uses the software. The major number is bumped when backward incompatible changes are introduced.

Ok, there is a fourth number: the pre-release number suffixed to the version after the b letter (for beta), example: 1.2.3b7. The pre-release number is here to indicate that the software will soon be released as 1.2.3.

To retrieve the specific sources which were used to build a release, for example version 1.0.0b7 use the tag:

git clone git:// v1.0.0b7


Three steps :

  1. As the user may request a version change, or because the version must be incremented between two uploads, prior to build the new version must be pushed wherever the version is mentionned :

    • in the documentation (in doc/,
    • in the Python packaging configuration (in the [#]_,
    • and in the Wordish python module itself, ( in the module constant __version__).
    • The version file will also be used when building the man page as well as when building debian and fedora packages.

    This step is skipped if no upload and no version change was requested.

    The version is kept in a file named version and is pushed explicitly in the files with sed. The file should not read and depend on the version file at execution time, because at install time the version file is not available anymore.

    The inclusion of the version in the software module make it possible for users of the module to adapt their use to multiple wordish version depending on the software module version.

    Before commiting, the’s long_description parameter and the README.txt are also updated with the latest docstring from the wordish module.

  2. The tests are tried, the documentation is rebuilt, the package is rebuilt. Any error bailout the release script. This step is idempotent except for the documentation in the gh-branch which gets commited (not pushed).

    The scripts stops here if upload was not specified as an argument.

  3. If an upload was requested, if the repository is not clean or if the current branch is not master, the script bails out.

In the wordish sources, the version is kept in the file named version. The version is inserted :

The long description in the Python packaging configuration (in the, is also updated from the wordish module docstring.


There are four sources for documentation:

  1. the wordish module docstrings which is copied into README.txt, the long description of the,
  2. the doc/ directory which is transformed into html pages stored in the branch gh-pages. This is a special convention of github which interpret these file to be presented on the project page.
  3. the sources for the man pages in the man/ directory are restructured text pages built into the man format
  4. the wordish public API is described in the file


Wordish is available on the Python package index, writing only a file