Card Stories - Packaging and Distribution Documentation

A python package, a Debian GNU/Linux package and a twistd plugin are bundled together. The server side tests and client side tests can be run with a single command.

=Packaging=

setup.py
The setup.py exists in conformance to the distutils python requirements. The reference documentation for each fields complements the guide. It is best understood by reading an example such as the django setup.py.

The setup.py file alone describes the binary distribution created with

but it must be complemented with a MANIFEST.in file as explained in the source distribution documentation.

There is no support to run tests at this time.

Debian GNU/Linux
A native package exists, meaning the debian package is part of the source distribution and is maintained by the author of the package. The static files, including the JavaScript client are copied to /usr/share/cardstories. The database is stored in /var/cache/cardstories. The daemon is launched by an init file using the twistd plugin architecture.

The presence of the setup.py file at the root of the source tree is automatically detected by debhelper 7 and used to figure out the layout of the Debian package.

twistd plugin
The plugin is installed in /etc/cardstories and its integration can be seen with :

If it needs to be run manually, the usage can be displayed with:

=Tests=

The maintain.mk file at the root of the source tree runs the tests with

The client side tests are run from a web browser and should display at the bottom of the page:

=Automated AGPL compliance=

A webservice partially automating the publication of server side sources licensed under the AGPL is included with the cardstories game. It could be reused in different contexts to help the occasional hacker to comply with the terms of the AGPL.

The primary reason for an author to use the AGPL instead of the GPL is to display a link to the server sources, as explained in the preamble:

''…if your program is a web application, its interface could display a “Source” link that leads users to an archive of the code. There are many ways you could offer source, and different solutions will be better for different programs; ''

When deploying an AGPL application server side, care must be taken to provide a way for the user to download the corresponding sources, including the local modifications:

''Notwithstanding any other provision of this License, if you modify the Program, your modified version must prominently offer all users interacting with it remotely through a computer network (if your version supports such interaction) an opportunity to receive the Corresponding Source of your version by providing access to the Corresponding Source from a network server at no charge, through some standard or customary means of facilitating copying of software. ''

If the software is a webservice serving static files such as cardstories, the original sources could be included in an archive available at the same location ( for instance http://cardstories.dachary.org/cardstories/static/cardstories.zip ) and a link added in each page visible to the user.

Republishing server sources
If someone implements a quick but useful hack in the code, the overhead of the compliance is comparatively high. For a few lines of patch in a python file, one would need to rebuild a source distribution. For cardstories It could be done as follows on Debian GNU/Linux :

It is a fairly long sequence of commands and it requires a knowledge of Debian GNU/Linux packaging that may not be available, even to a seasoned python hacker.

Automated source archive creation
A path in the webservice builds an archive containing the server side sources from the installed files instead of using the source files from the original distribution. A first version is implemented in cardstories to collect the files that would not be visible if browsing the static tree served by the webservice, i.e.


 * site.py
 * service.py
 * tap.py

The code triggered by the /agpl path is as follows:

This automation only addresses a specific case of AGPL compliance though. When more complex modifications are made to the software or its dependencies, there is a need for a careful update of the complete and corresponding source.