Hacking on GinsFSM
==================
Here are some guidelines about hacking on GinsFSM.
Using a Development Checkout
----------------------------
Below is a quick start on creating a development environment using a GinsFSM
checkout.
TODO
Adding Features
---------------
In order to add a feature to GinsFSM:
- The feature must be documented in both the API and narrative
documentation (in ``docs/``).
- The feature must work fully on the following CPython versions: 2.6,
2.7, and 3.2 on both UNIX and Windows.
- The feature must work on the latest version of PyPy.
- The feature must not cause installation or runtime failure on App Engine.
If it doesn't cause installation or runtime failure, but doesn't actually
*work* on these platforms, that caveat should be spelled out in the
documentation.
- The feature must not depend on any particular persistence layer
(filesystem, SQL, etc).
- The feature must not add unnecessary dependencies (where
"unnecessary" is of course subjective, but new dependencies should
be discussed).
The above requirements are relaxed for scaffolding dependencies. If a
scaffold has an install-time dependency on something that doesn't work on a
particular platform, that caveat should be spelled out clearly in *its*
documentation (within its ``docs/`` directory).
Coding Style
------------
- PEP8 compliance. Whitespace rules are relaxed: not necessary to put
2 newlines between classes. But 80-column lines, in particular, are
mandatory.
Running Tests
--------------
- To run tests for GinsFSM on a single Python version, run ``python setup.py
test`` against the using the Python interpreter from virtualenv into which
you've ``setup.py develop``-ed GinsFSM.
- To run the full set of GinsFSM tests on all platforms, install ``tox``
(http://codespeak.net/~hpk/tox/) into a system Python. The ``tox`` console
script will be installed into the scripts location for that Python. While
``cd``'ed to the GinsFSM checkout root directory (it contains ``tox.ini``),
invoke the ``tox`` console script. This will read the ``tox.ini`` file and
execute the tests on multiple Python versions and platforms; while it runs,
it creates a virtualenv for each version/platform combination. For
example::
$ /usr/bin/easy_install tox
$ cd ~/hack-on-ginsfsm/ginsfsm
$ /usr/bin/tox
Test Coverage
-------------
- The codebase *must* have 100% test statement coverage after each commit.
You can test coverage by installing ``nose`` and ``coverage``
into your virtualenv, and running ``setup.py nosetests --with-coverage``.
Documentation Coverage
----------------------
- If you fix a bug, and the bug requires an API or behavior
modification, all documentation in this package which references
that API or behavior must change to reflect the bug fix, ideally in
the same commit that fixes the bug or adds the feature.
- To build and review docs:
1. Install ``tests_require`` dependencies from GinsFSM's setup.py into your
virtualenv.
2. From the ``docs`` directory of the GinsFSM checkout run ``make html
SPHINXBUILD=/path/to/your/virtualenv/bin/sphinx-build``.
3. Open the _build/html/index.html file to see the resulting rendering.
Change Log
----------
- Feature additions and bugfixes must be added to the ``CHANGES.txt``
file in the prevailing style. Changelog entries should be long and
descriptive, not cryptic. Other developers should be able to know
what your changelog entry means.