HACKING

Notes for anyone hacking crosscat

* Automatic tests

Every commit on long-term branches including master should pass

   % ./check.sh

which builds crosscat and runs the automatic tests.  Please run this
in your .git/hooks/pre-commit script during development, and in each
commit please add or update automatic tests for any bugs you add or
features you fix in the that commit.

check.sh does a clean build of crosscat into the build/ directory and
then either runs `py.test tests shell', if you pass it no arguments;
or runs py.test with the arguments supplied.

Thus, if you're hacking a limited part of crosscat, you can, e.g.,
run a subset of tests, and stop at the first failure, with

   % ./check.sh -x tests/test_frobnitz.py

However, please double-check that every commit you have made passes
all tests before publishing the commits.

* Versions

Our version scheme, compatible with PEP 440:

    <major>.<minor>[.<teeny>]a<date>    (prerelease snapshot)
    <major>.<minor>[.<teeny>]rc<N>      (release candidate)
    <major>.<minor>[.<teeny>]           (release)

We do not currently make any semantic API compatibility guarantees
about the meaning of <major>, <minor>, and <teeny>.

In the source tree, the VERSION file contains either the current
release version number, or the most recent tagged version number
followed by a plus sign `+'.  In that case, a suffix will be added to
the most recent version number, derived from `git describe', of the
form:

    .post<N>+g<commitid>[.<dirty>]

The Git tag for a tagged version is named with a `v' prefix.  Note
that the content of VERSION for any tagged version MUST NOT include a
`+' suffix, so that `cat VERSION' is sufficient to find the version
number, and `git describe' is not necessary.

To tag a new version:

1. Set VERSION to the new version, say `0.2.42':

    % echo 0.2.42 > VERSION
    % git commit -m 'Bump version to 0.2.42.' VERSION

2. Tag it with an annotated tag:

    % git tag -a -m v0.2.42 v0.2.42

   If you want, you can include release notes in the annotated tag
   message.

3. Append `+' to the version in VERSION:

    % echo 0.2.42+ > VERSION
    % git commit -m 'Bump version to 0.2.42+.' VERSION

There is a handy script that automates most of the above:
  https://github.com/gregory-marton/git-porcelain/blob/master/src/git-bump
Please do write meaningful change logs.

* Branches

We prefer pull-request branches to be named as YYYYMMDD-USERNAME-TOPIC,
e.g. 20150910-riastradh-tests.

Every functional change should bump the version number (see Versions above).
Limited non-functional changes, e.g. to README or HACKING, may occur
on master without a branch or version number bump.

* Tests

If you add new functionality, add automatic tests for it.  If you fix
something that the automatic tests don't detect, add tests for it and
make sure they fail without your fix.  If you break the tests, fix
them.

* Platforms:

    * Ubuntu 14.04 LTS and recent OS X are supported.
    * C++ code should be compatible with C++03.
    * New Python code should be in the same style as Bayeslite: Doubled blank
      lines are not necessary, and continuation lines should be indented four
      spaces instead of aligned.