Some issues are tedious to deal with ona regular basis, for examples:
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 (http://github.com/jdb/wordish/), 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://github.com/jdb/wordish.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: http://jdb.github.com/wordish/.
There is an issue tracker at http://github.com/jdb/wordish/issues.
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
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://github.com/jdb/wordish.git v1.0.0b7
Three steps :
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 :
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 setup.py 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 setup.py’s long_description parameter and the README.txt are also updated with the latest docstring from the wordish module.
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.
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 setup.py), is also updated from the wordish module docstring.
There are four sources for documentation:
Wordish is available on the Python package index, writing only a file