Contributing¶
Contributions are welcome, and are greatly appreciated! Every little bit helps, and credit will be given. Feel free to join our Facebook group if you have any questions about how to get started.
Bug reports¶
Please report bugs by opening a new issue in our GitHub repository. It is most helpful if you can include:
- How Tabbycat was installed (on Heroku, locally on OS X, etc.)
- Any details about your tournament and setup that might be helpful in troubleshooting
- Detailed steps for how to reproduce the bug
Getting started¶
- To easily test your changes to Tabbycat you probably want a working local install (without using Docker)
- Generally we prefer that features and bug fixes are submitted as pull requests on their own branch (as described in the git-flow workflow). Submitting against develop (but not master) is fine for small fixes and changes.
- We use Django’s testing tools — it would be great if new features came with unit tests
Style guide¶
We use flake8 to check for a non-strict series of style rules. Warnings will trigger a Travis CI build to fail. The entire codebase can be checked by using:
$ flake8 .
While in the base directory
Versioning convention¶
Our convention is to increment the minor version whenever we add new functionality, and to increment the major version whenever
- the database can’t be migrated forwards using
python manage.py migrate --no-input
, or - there is a major change to how the tournament workflow goes, or
- we make some other change that is, in our opinion, significant enough to warrant a milestone.
Most of the time, we write data migrations to allow existing systems to be upgraded easily. However, we don’t always support backward database migrations. Our expectation is that long-lived installations keep up with our latest version.
One day, we hope to have a public API in place to facilitate the integration with other debating tournament software, like registration or adjudicator feedback systems. If and when that happens, we’ll probably revise this convention to be more in line with Semantic Versioning.
Starting from version 0.7.0, we use code names for versions, being breeds of cats in alphabetical order.
Documentation¶
Documentation is created using Sphinx and hosted at Read The Docs. Pushes to develop
will update the latest documentation set, while pushes to master
will update the stable documentation set.
To preview the documentation locally, install the docs-specific requirements (from the base folder):
$ pip install -r 'docs/requirements.txt'
Then start the server:
$ sphinx-autobuild docs docs/_build/html --port 7999
You should then be able to preview the docs at 127.0.0.1:7999.
Release Checklist¶
- Check that all migrations have been generated and committed into Git
- Bump version number in
docs/conf.py
- Bump version number and (if applicable) codename in
tabbycat/settings.py
- Update the main
CHANGELOG.rst
file - Check that the last Travis CI build passed
- Check that
deploy_heroku.py
still works - Shift remaining issues from the Github Milestone
- Create and finish the release branch as per git-flow
- Ensure the tag is correct (
vX.Y.Z
) and published to GitHub - Back-merge
master
to thekitten
branch - Back-merge
develop
to the in-progress feature branches - Push
master
to the release pipeline repository - Issue a formal release with change notes on GitHub
- Post change notes on the Facebook group