😸 Tabbycat User Guide¶
Tabbycat is a draw tabulation system for two-team parliamentary debate tournaments. It supports the Australs, NZ Easters, Australian Easters, Joynt Scroll, UADC and WSDC formats, and is highly configurable, supporting many custom variations of the above formats too.
Installing on Heroku¶
When running Tabbycat on the internet, we set it up on Heroku. The project is set up to be good to go on Heroku, and it works well for us, so if you’d like to run it online, we recommend that you do the same. Naturally, this requires you to have a Heroku account.
Installation—the short way¶
Click this button:
This is the easiest way to deploy an instance of Tabbycat online. It requires no technical background.
If you don’t already have a Heroku account, it’ll prompt you to create one. Once you’re logged in to Heroku, choose a name for your installation, then scroll down and click Deploy. Once it’s finished, click View and follow the prompts. Once finished, open the site and from there you can easily set up a demo data set (if you just want to learn Tabbycat) or use the data importer to set up a real tournament.
Note
During the setup process Heroku will ask you to verify your account by adding a credit or debit card. A standard Tabbycat site will not charge your card without explicit permission — charges only accrue if you deliberately add a paid service in the Heroku dashboard.
That said if you do not have access to a credit/debit card we offer a version of the software — ‘Tabbykitten’ — that does not require Heroku to verify your account. However, as a result, this version is limited: it does not send error reports to the developers and can handle much less public traffic. We strongly recommend using it only as a last resort, and even then only for small tournaments. Use this link to set up a Tabbykitten site.
If you have a background in programming, you might prefer the method below.
Installation—the long way¶
The long way sets you up with more control over your environment. Because you’ll clone our GitHub repository, it’ll be easier for you to pull and contribute updates to the source code. We recommend it if you have experience with Git. It’s also easier with this method to import CSV files using the command-line importer, so if you have a very large tournament, this might make importing initial data easier.
We’ve tested these instructions successfully on Windows, Linux and Mac OS.
Requisite technical background¶
You need to have at least a passing familiarity with command-line interfaces to get through the longer traditional method. We’ll talk you through the rest.
When we say “command shell”, on Windows we mean Command Prompt, and on Linux and OS X we mean Terminal (or your favourite command shell).
Advanced users
Tabbycat is a Django project. As such, it can be installed on any web platform that supports Django, using any SQL system that Django supports. Just be aware that we haven’t tried any other platform.
Short version¶
git clone https://github.com/czlee/tabbycat.git git checkout v1.3.1 # or master cd tabbycat python deploy_heroku.py <yourappname>
If you want to import tournament data from CSV files, put them in data/<yourtournamentname>
, then:
git commit -am "Add data for <yourtournamentname>"
git push heroku master
heroku run tabbycat/manage.py importtournament <yourdatadirectoryname> --slug <slug> --name <Your Awesome Tournament> --short-name <Awesome>
1. Install dependencies¶
- Install the Heroku Command Line Interface (CLI), then log in with the command
heroku login
. - Windows users need to install Python. Follow (only!) part 1(a) of our Windows instructions.
- If you don’t already have Git, follow the instructions on the GitHub website to set up Git.
Note
Linux and OS X users probably already have Python installed. There is no need to install Python 3 specifically. Although Tabbycat uses Python 3, installing it on Heroku relies only on the deployment script, which is compatible with both Python 2 and Python 3.
2. Get the source code¶
Open a command shell. Navigate to an appropriate directory on your computer using cd
(creating directories using mkdir
as appropriate), then run:
git clone https://github.com/czlee/tabbycat.git git checkout v1.3.1 # or master
Tip
If this is your second time creating a Tabbycat instance on Heroku from this computer, you don’t need to clone the repository a second time. Just run git pull
to update the code to the latest version, and press ahead to step 3: Deploy to Heroku.
3. Deploy to Heroku¶
Navigate to your Tabbycat directory:
cd path/to/my/tabbycat/directory
Run the script to deploy the app to Heroku. Replace
<yourappname>
with your preferred URL. Your website will be at<yourname>.herokuapp.com
.
python deploy_heroku.py <yourappname>This script has other options that you might find useful. Run
python deploy_heroku.py --help
for details.Note
If you’d prefer to import tournament data locally and push the database to Heroku using
heroku pg:push
, use the--no-init-db
option to preventdeploy_heroku.py
from running initial migrations on the database.Note
If this isn’t your first tournament, the
heroku
Git remote might already be pointing to your first tournament. In this case, you should use the--git-remote <new_remote_name>
option to get the script to create a new git remote for you, so you can use when importing tournament data.When this script finishes, it will open the app in your browser. It should look something like this:
4. Import tournament data¶
Note
This step is optional and there are other methods of importing data. However the following method is most useful for large tournaments where manual entry would be tedious.
In order to use the importtournament
command directly on the server, your data also needs to be on the server. The easiest way to get this data on to the server is to make a Git commit and git push
it to the server.
Place your CSV files in
data/yourtournamentname
, as described in Importing Initial Data.Commit and push:
git commit -am "Add data for <yourtournamentname>" git push heroku master
Note
If you use
--git-remote
in step 3 to create your own Git remote, you should use that remote name instead ofheroku
in the last command above.Advanced users
You might like to create a new branch to keep this data off your master branch.
Run this command, replacing
<fields>
with your own names:heroku run tabbycat/manage.py importtournament <yourdatadirectoryname> --slug <slug> --name <Your Awesome Tournament> --short-name <Awesome>
Heroku options you may want to change¶
If you have a large tournament, you may want to customize your Heroku app. This section provides some guidance on upgrades and settings you may wish to consider. Some of these configurations require you to have the Heroku Command Line Interface (CLI) installed.
Upgrading your database size¶
The free plan of Heroku Postgres, “Hobby Dev”, should work for most small tournaments. For large tournaments, however, you may find that you exceed the 10,000-row limit of this plan. It’s difficult to give general guidance on how many rows you’re likely to use, because it depends on which features of Tabbycat you use (e.g., if you use adjudicator feedback). But to give some idea, Australs 2016, which had 74 teams and 8 preliminary rounds and used adjudicator feedback, ended up at around 30,000 rows.
If you need more than 10,000 rows, you’ll need to upgrade to a paid Heroku Postgres Plan. The 10,000,000 rows allowed in the lowest paid plan, “Hobby Basic”, should certainly be more than sufficient.
If you’re not sure, you can always start at Hobby Dev—just be prepared to upgrade during the tournament if you run close to capacity.
Custom domain names¶
Your Heroku app will be available at yourappname.herokuapp.com
. You may want it to be a subdomain of your tournament’s website, like tab.australasians2015.org
. If so, you’ll need to configure your custom domain and SSL. Instructions for both are in the Heroku Dev Center:
The custom domain name basically requires two things: a DNS CNAME
entry on your website targeting yourappname.herokuapp.com
, and the custom domain configured on Heroku using heroku domains:add tab.yourwebsite.com
. You’ll also need to provide an SSL certificate for your custom domain and add it using the heroku certs:add
command.
HTTPS¶
Starting from version 1.3, all Tabbycat sites deployed to Heroku will redirect all traffic to HTTPS by default.
For a myriad of reasons, we strongly advise against disabling this. But if for some reason you need to run on plain HTTP, you can do this by setting the DISABLE_HTTPS_REDIRECTS
config variable in Heroku to disable
(see Heroku documentation on config vars). The value of the config var must be disable
; if it’s anything else, HTTPS redirects will remain in place.
Tip
Most modern browsers, after having been redirected by a site to HTTPS once, remember that that site requires HTTPS and go there for all subsequent visits even if the user typed in a plain http:// address. It may do this because it cached the HTTP 301 permanent redirect, stored an HSTS entry and/or tagged its session cookie to require HTTPS. If, after disabling HTTPS on your Tabbycat site, you find that you’re still being redirected to HTTPS, first try a browser or computer that hasn’t visited the site before. If that works, then remove the relevant entry from your (original) browser’s cache, HSTS set and cookies, and try again.
Local Installations¶
What is a local installation?¶
Tabbycat is a web-based system: it’s designed to run as a web site. However, instead of installing it on a web server, you can install it on your computer, serving web pages to yourself. This is called a local installation.
Then, when you open your browser, you can use Tabbycat like any other web site. The only difference is that this one is on your computer, not some computer in a data centre in a far-away land. In effect, you are getting your computer to behave like a web server.
Should I use a local installation?¶
In most cases, you should make an online Tabbycat installation by setting up an instance on Heroku. This has a number of major advantages:
- The installation process is easier.
- You can enter ballots and manage your tournament from multiple computers.
- Participants can access the draw, motions, results and more online.
- Heroku’s data centers are less likely to fail than your computer is.
- Heroku e-mails Tabbycat’s developers error reports to help us fix bugs.
In some cases, you might have a good reason to use a local installation. We can think of just one such reason: If you won’t have access to the internet at your tournament, or if internet access will be flaky, then you should use a local installation.
Attention
You’ll need internet access to download dependencies during the local installation process. So if you’re not expecting to have reliable internet access at your tournament, be sure to have Tabbycat installed before you get there!
Advanced users
Tabbycat is a Django project, so if you have your own preferred method of running Django projects, you can also do that. Just be aware that we haven’t tried it.
Okay, so how do I do it?¶
The easiest option is to install Tabbycat using Docker. This method should work across all operating systems and is by far the easiest way to get a local copy running.
If installing using Docker does not work, or if you want to be able to modify Tabbycat’s code we also have a number of instructions for manually setting up a copy of Tabbycat. There instructions are here:
Advanced uses¶
Can others access my local install?¶
Local installations can also take advantage of multiple-computer site access, including data entry—it’s just takes more work than a Heroku installation to set up.
Since a local installation is just having your computer run a web server, it can serve other computers too. You can make this work even if you don’t have internet access: all you need is a router that you can use to connect a few computers together. Then other computers on your local network can access the Tabbycat site hosted on your computer. We did this at Victoria Australs 2012.
We don’t provide detailed instructions for this; we leave it for advanced users to set up themselves. As a rough guide:
- You need to pass in your computer’s IP address and port to the runserver command, for example, if your computer (the one acting as a server) is 196.168.0.2 and you want to run it on port 8000:
dj runserver 192.168.0.2:8000
- You need to configure your firewall settings to allow incoming connections on the IP address and port you specified in that command.
- Be aware that local installs use the Django development server, whose security is not tested. Therefore, it’s a good idea to make sure your firewall only lets in computers on your local network (or, if you’re really paranoid, isolate the network from the internet completely).
Can I run an internet-accessible website from a local installation?¶
Probably not. Even if you disable your firewall, chances are your home router (or university router) will block any connections from the outside world to you. Even if you can though, you really shouldn’t. The local installation uses the Django development server, which is a lightweight server designed for developers. Specifically, Django does not test the security of its development server in the way that proper web servers do. That is: It’s a security risk to run a local installation as an internet-accessible site. Don’t do it. Install Tabbycat on Heroku instead.
Alternatively, if you have a background in web development, you might choose to install Tabbycat on your own production server. It’s a Django project, so any means of supporting Django projects should work fine.
It’s safe to run on a small, isolated network (see above) with your firewall correctly configured because you presumably trust everyone you let on the network!
Installing Locally using Docker¶
Is this the best install method for you?
In most cases, we recommend doing an internet-based installation on Heroku instead. If you decide to do a local installation, be sure to read our page on local installations to help you understand what’s going on, particularly this section: Should I use a local installation?
Attention
This installation method is newly available in version 1.2. As such, it hasn’t been extensively tested. If you encounter any difficulties, please report the issue on GitHub or (less preferably) contact the developers.
Docker is an application that makes it very easy to load and run a specific collection of software. It allows us to bundle everything necessary to run Tabbycat into a single package rather than have users install everything needed step-by-step. Once set up, Docker will allow you to start and stop a webserver (that in turn runs Tabbycat) on your computer whenever you want and without the need for internet access.
1. Download Tabbycat¶
- Go to the page for our latest release.
- Download the zip or tar.gz file.
- Extract all files in it to a folder of your choice.
2. Install Docker¶
If using OS X or Linux¶
- Install the Docker App from the Docker downloads page.
If using Windows 10 Pro, Enterprise, or Education Edition¶
- Install the Docker App from the Docker downloads page.
- Before or shortly after installing it, Docker may ask you to enable hypervisor and restart your PC. If it asks you this follow the prompts and restart as asked.
- Once Docker has finished installing, open up the newly-installed Docker application, then right-click the app’s icon (the whale) in the Taskbar.
- From there, hit Settings in the menu and Shared Drives in the sidebar. Tick the checkbox next to your hardrive and then click Apply. After that has applied exit and reopen the docker app (ie right-click the taskbar icon and hit exit) and verify that the checkbox is still there.
If using Windows 7, Windows 8, or Windows 10 Home Edition¶
- Install the Docker Toolbox from the Docker Toolbox downloads page.
Tip
Not sure which edition of Windows you have? Click Start, search for “System”, and open the Control Panel item “System”.
3. Run Tabbycat in Docker¶
If using the Docker App¶
These instructions apply if you installed the Docker App, i.e., if you are using Mac OS X, Linux or Windows Pro/Enterprise/Education.
Ensure that Docker application is open (there should be a whale icon in your menu/task bar) and that it says that Docker is running.
Browse to the location where you extracted Tabbycat to. Open up the bin folder there. Within that folder:
- If you’re on OS X, press the Control key, click the icon for osx_docker_start.command, then choose Open from the shortcut menu.
- If you’re on Windows, open windows_docker_start.bat.
- If you’re on Linux, open up a terminal in the Tabbycat folder (i.e. the folder containing
README.md
) and rundocker-compose up
.
A terminal window should popup and bunch of text scroll by. If this is your first time running Docker it may take a while (30 minutes or more) to download the virtual machine. When the text has stopped scrolling by you should see a Finished building Tabbycat! message.
Open up http://localhost:8000/ (Windows) or http://0.0.0.0:8000 (OSX/Linux) in a browser of your choice!
Note
If you want to reopen Tabbycat at a later time (say after restarting) repeat steps 1 through 4 here.
If using the Docker Toolbox¶
These instructions apply if you installed the Docker Toolbox, i.e., if you are using Windows 7, Windows 8 or Windows 10 Home.
Start the Docker Quickstart Terminal.
Run the command
docker-machine ip
. Take note of the IP address it shows, for example:$ docker-machine ip 192.168.99.100
Navigate to the Tabbycat folder (i.e. the folder containing
README.md
) and rundocker-compose up
.Open a browser and go to http://192.168.99.100:8000/, replacing “192.168.99.100” with whatever IP address was shown in step 2.
Once you’re done and want to stop the Tabbycat server, press Ctrl+C, wait until the next prompt appears, and then run
docker-machine stop
.
Note
If you want to reopen Tabbycat at a later time (say after restarting) repeat steps 1 through 4 here.
Installing Locally on Linux¶
Is this the best install method for you?
In most cases, we recommend doing an internet-based installation on Heroku instead. If you decide to do a local installation, be sure to read our page on local installations to help you understand what’s going on, particularly this section: Should I use a local installation?
If you just want to quickly set up a copy of Tabbycat to run locally on Linux, we recommend installing using Docker, which is much easier than the process below.
Requisite technical background¶
You need to be familiar with command-line interfaces to get through this comfortably. While a background in the specific tools (Python, etc.) we use will make things easier for you, it’s not necessary: we’ll talk you through the rest.
Advanced users
Tabbycat is a Django project, so can be installed in any manner that Django projects can normally be installed. For example, if you prefer some SQL system other than PostgreSQL, you can use it so long as it’s Django-compatible. Just be aware that we haven’t tried it.
Short version¶
curl -sL https://deb.nodesource.com/setup_5.x | sudo -E bash - # add Node.js source repository sudo apt-get install python3-dev python3-venv postgresql-9.6 postgresql-server-dev-9.6 nodejs # either wget https://github.com/czlee/tabbycat/archive/v1.3.1.tar.gz tar xf v1.3.1.tar.gz cd tabbycat-1.3.1 # or git clone https://github.com/czlee/tabbycat.git git checkout v1.3.1 # or master sudo -u postgres createuser myusername --pwprompt # skip if not first time sudo -u postgres createdb mydatabasename --owner myusername
Then create local_settings.py as described below, then:
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements_common.txt
npm install
cd tabbycat
dj migrate
dj collectstatic
dj createsuperuser
waitress-serve wsgi:application
1. Install dependencies¶
First, you need to install all of the software on which Tabbycat depends, if you don’t already have it installed.
Advanced users
These instructions are for Ubuntu 14.04 and higher. If you have another distribution of Linux, we trust you’ll know how to navigate the package manager for your distribution to install the dependencies.
1(a). Python¶
Tabbycat requires Python 3.4 or later. You probably already have Python 3.4, but you’ll also need the development package in order to install Psycopg2 later. The venv
module will come in handy too. Install:
$ sudo apt-get install python3-dev python3-venv
Check the version:
$ python3 --version
Python 3.4.4
Warning
Tabbycat does not support Python 2. You must use Python 3.4 or later.
Advanced users
If you prefer, you can use Virtualenv instead of Python’s built-in venv
module.
1(b). PostgreSQL¶
PostgreSQL is a database management system.
You’ll need the server-dev package in order to install Psycopg2 later. As per the PostgreSQL installation instructions:
$ sudo apt-get install postgresql-9.6 postgresql-server-dev-9.6
If using Ubuntu <14.10 substitute “postgresql-9.3” for “postgresql-9.6” in the above commands.
1(c). Node.js/NPM¶
Node.js is a JavaScript runtime.
Tabbycat requires Node and its package manager to compile front-end dependencies. Install using:
$ sudo apt-get install curl
$ curl -sL https://deb.nodesource.com/setup_5.x | sudo -E bash -
$ sudo apt-get install -y nodejs
$ sudo ln -s /usr/bin/nodejs /usr/bin/node
2. Get the source code¶
Download and extract:
$ wget https://github.com/czlee/tabbycat/archive/v1.3.1.tar.gz $ tar xf v1.3.1.tar.gz $ cd tabbycat-1.3.1
If you’ve used Git before, you might prefer to clone our GitHub repository instead:
$ git clone https://github.com/czlee/tabbycat.git $ git checkout v1.3.1 # or master
Tip
You might like to fork the repository first, to give yourself a little more freedom to make code changes on the fly (and potentially contribute them to the project).
3. Set up a new database¶
Hint
You can skip step 1 if this is not your first installation. Every Tabbycat installation requires its own database, but they can use the same login role if you like.
- Create a new user account with a password, replacing
myusername
with whatever name you prefer. If you don’t know what username to pick, usetabbycat
.
$ sudo -u postgres createuser myusername --pwpromptTip
If you’ll be running multiple instances of Tabbycat, developing, or diving into the database yourself, you might find it convenient to set up client authentication so that you don’t need to do all manual operations from
sudo -u postgres
. See the PostgreSQL documentation on client authentication for more information. For example, you could add alocal all myusername md5
line to the pg_hba.conf file, or you could define a mapping in pg_ident.conf and append themap=
option to thelocal all all peer
line in pg_hba.conf. If you want your new PostgreSQL account to be able to create databases, add--createdb
to the above command.
Create a new database, replacing
mydatabasename
with whatever name you prefer, probably the name of the tournament you’re running:$ sudo -u postgres createdb mydatabasename --owner myusername
4. Install Tabbycat¶
Almost there!
Navigate to your Tabbycat directory:
$ cd path/to/my/tabbycat/directory
- Start a new virtual environment. We suggest the name
venv
, though it can be any name you like:
$ python3 -m venv venv
Run the
activate
script. This puts you “into” the virtual environment:$ source venv/bin/activate
Install Tabbycat’s requirements into your virtual environment:
$ pip install --upgrade pip $ pip install -r requirements_common.txt $ npm install
Navigate to the tabbycat sub folder and copy local_settings.example to local_settings.py. Find this part in your new local_settings.py, and fill in the blanks as indicated:
DATABASES = { 'default': { 'ENGINE' : 'django.db.backends.postgresql_psycopg2', 'NAME' : '', # put your PostgreSQL database's name in here 'USER' : '', # put your PostgreSQL login role's user name in here 'PASSWORD': '', # put your PostgreSQL login role's password in here 'HOST': 'localhost', 'PORT': '5432', } }
Navigate to the tabbycat sub-directory, initialize the database, compile the assets, and create a user account for yourself:
$ cd tabbycat $ dj migrate $ dj collectstatic $ dj createsuperuser
Start Tabbycat!
$ waitress-serve wsgi:applicationIt should show something like this:
serving on http://0.0.0.0:8080
- Open your browser and go to the URL printed above. (In the above example, it’s http://0.0.0.0:8080.) It should look something like the screenshot below. If it does, great! You’ve successfully installed Tabbycat.
Naturally, your database is currently empty, so proceed to importing initial data.
Starting up an existing Tabbycat instance¶
To start your Tabbycat instance up again next time you use your computer:
$ cd path/to/my/tabbycat/directory
$ source venv/bin/activate
$ cd tabbycat
$ waitress-serve wsgi:application
Installing Locally on OS X¶
Is this the best install method for you?
In most cases, we recommend doing an internet-based installation on Heroku instead. If you decide to do a local installation, be sure to read our page on local installations to help you understand what’s going on, particularly this section: Should I use a local installation?
If you just want to quickly set up a copy of Tabbycat to run locally on OS X, we recommend installing using Docker, which is much easier than the process below.
Requisite technical knowledge¶
You need to be familiar with command-line interfaces to get through this comfortably. While a background in the specific tools (Python, etc.) we use will make things easier for you, it’s not necessary: we’ll talk you through the rest. You just need to be prepared to bear with us. It’ll take a while the first time, but it gets easier after that.
Every line in the instructions that begins with $
is a command that you need to run in a Terminal, but without the $
: that sign is a convention used in instructions to make it clear that it is a command you need to run.
Advanced users
Tabbycat is a Django project, so can be installed in any manner that Django projects can normally be installed. For example, if you prefer some SQL system other than PostgreSQL, you can use it so long as it’s Django-compatible. Just be aware that we haven’t tried it.
1. Install dependencies¶
First, you need to install all of the software on which Tabbycat depends, if you don’t already have it installed.
1(a). Python¶
Tabbycat requires Python 3.4 or later. OS X only comes with Python 2.7, so you’ll need to install this. You can download the latest version from the Python website.
The executable will probably be called python3
, rather than python
. Check:
$ python3 --version
Python 3.4.4
Warning
Tabbycat does not support Python 2. You must use Python 3.4 or later.
Advanced users
These instructions will use the venv
module. If you prefer, you can use Virtualenv instead.
1(b). PostgreSQL¶
Download postgres.app, move it to your Applications folder, and open it. This should place an icon in your menu bar, showing that the postgres database is running. Whenever you are running Tabbycat you’ll need to have this app running.
1(c). Node.js/NPM¶
Download and run the node.js Mac OS X Installer (.pkg)
2. Get the source code¶
- Go to the page for our latest release.
- Download the zip or tar.gz file.
- Extract all files in it to a folder of your choice.
Advanced users
If you’ve used Git before, you might prefer to clone our GitHub repository instead. Don’t forget to check out the v1.3.1 tag or the master branch.
Even better, you might like to fork the repository first, to give yourself a little more freedom to make code changes on the fly (and potentially contribute them to the project).
3. Set up a new database¶
Hint
You can skip step 1 if this is not your first installation. Every Tabbycat installation requires its own database, but they can use the same login role if you like.
- Create a new user account with a password, replacing
myusername
with whatever name you prefer. If you don’t know what username to pick, usetabbycat
.
$ createuser myusername --pwpromptTip
If you’ll be running multiple instances of Tabbycat, developing, or diving into the database yourself, you might find it convenient to set up client authentication so that you don’t need to do all manual operations from
sudo -u postgres
. See the PostgreSQL documentation on client authentication for more information. For example, you could add alocal all myusername md5
line to the pg_hba.conf file, or you could define a mapping in pg_ident.conf and append themap=
option to thelocal all all peer
line in pg_hba.conf. If you want your new PostgreSQL account to be able to create databases, add--createdb
to the above command.
Create a new database, replacing
mydatabasename
with whatever name you prefer, probably the name of the tournament you’re running:$ createdb mydatabasename --owner myusername
In terminal type in:
$ PATH="/Applications/Postgres.app/Contents/Versions/9.6/bin:$PATH"
4. Install Tabbycat¶
Almost there!
Navigate to your Tabbycat directory:
$ cd path/to/my/tabbycat/directory
Copy local_settings.example to local_settings.py. Find this part in your new local_settings.py, and fill in the blanks as indicated:
DATABASES = { 'default': { 'ENGINE' : 'django.db.backends.postgresql_psycopg2', 'NAME' : '', # put your PostgreSQL database's name in here 'USER' : '', # put your PostgreSQL login role's user name in here 'PASSWORD': '', # put your PostgreSQL login role's password in here 'HOST': 'localhost', 'PORT': '5432', } }
Start a new virtual environment. We suggest the name
venv
, though it can be any name you like:$ python3 -m venv venv
Run the
activate
script. This puts you “into” the virtual environment:$ source venv/bin/activate
Install Tabbycat’s requirements into your virtual environment:
$ pip install --upgrade pip $ pip install -r requirements_common.txt $ npm install
Navigate to the tabbycat sub folder, initialize the database, compile the assets, and create a user account for yourself:
$ cd tabbycat $ dj migrate $ dj collectstatic $ dj createsuperuser
Start Tabbycat!
$ waitress-serve wsgi:applicationIt should show something like this:
serving on http://0.0.0.0:8080
- Open your browser and go to the URL printed above. (In the above example, it’s http://0.0.0.0:8080/.) It should look something like the screenshot below. If it does, great! You’ve successfully installed Tabbycat.
Naturally, your database is currently empty, so proceed to importing initial data.
Starting up an existing Tabbycat instance¶
To start your Tabbycat instance up again next time you use your computer:
$ cd path/to/my/tabbycat/directory
$ source venv/bin/activate
$ cd tabbycat
$ waitress-serve wsgi:application
Installing Locally on Bash on Windows¶
Is this the best install method for you?
In most cases, we recommend doing an internet-based installation on Heroku instead. If you decide to do a local installation, be sure to read our page on local installations to help you understand what’s going on, particularly this section: Should I use a local installation?
If you just want to quickly set up a copy of Tabbycat to run locally on Windows, we recommend installing using Docker, which is much easier than the process below.
Requisite technical background¶
Bash on Windows is in beta, so you should be confident with command-line interfaces, have at least some experience with Linux and, most importantly, be willing to work with beta systems. This means that Bash on Windows isn’t yet fully stable and some features are incomplete. We’ve managed to get it going, but we haven’t rigorously tested it, so if you’re going to use this for a real tournament, you should either run an entire test tournament first or use a different installation method (like Docker).
If you’re not already familiar with Bash on Windows, you should be willing to familiarise yourself with it, including potentially things not mentioned in these instructions. While a background in the specific tools (Python, etc.) we use will make things easier for you, it’s not necessary: we’ll talk you through the rest.
Advanced users
Tabbycat is a Django project, so can be installed in any manner that Django projects can normally be installed. For example, if you prefer some SQL system other than PostgreSQL, you can use it so long as it’s Django-compatible. Just be aware that we haven’t tried it.
Differences from the Linux installation¶
For the most part, these instructions mirror those for doing local installations on Linux. The only difference is that, rather than installing PostgreSQL on Linux, you’ll install PostgreSQL for Windows. The reason for this is that PostgreSQL doesn’t yet work on the Windows Subsystem for Linux. As of February 2017, there is a fix on the Windows Insider Preview Build, but it’s still making its way to general availability.
This has a number of consequences:
- You’ll still install the PostgreSQL client on the Linux subsystem, using that to communicate with the server on Windows.
- Because you won’t install the PostgreSQL server, you need to install
libpq-dev
instead, in order for thepsycopg2
module to work. - These instructions will direct you to create the PostgreSQL role and database in pgAdmin, just like in the Windows instructions.
Short version¶
First, install PostgreSQL for Windows (on Windows, not on the subsystem for Linux). Once you’ve set it up, create a new role and database as instructed in the Windows instructions in section 3. Set up a new database. Then, in a Bash on Windows shell:
curl -sL https://deb.nodesource.com/setup_5.x | sudo -E bash - # add Node.js source repository sudo apt-get install python3-dev python3-venv libpq-dev postgresql-client-9.6 nodejs # either wget https://github.com/czlee/tabbycat/archive/v1.3.1.tar.gz tar xf v1.3.1.tar.gz cd tabbycat-1.3.1 # or git clone https://github.com/czlee/tabbycat.git git checkout v1.3.1 # or master
Then create local_settings.py as described in the Linux instructions, then:
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements_common.txt
npm install
cd tabbycat
dj migrate
dj collectstatic
dj createsuperuser
waitress-serve wsgi:application
1. Install dependencies¶
Follow these instructions:
- 1(a). Python in the Linux instructions, on the Bash subsystem
- 1(b). PostgreSQL in the Windows instructions (in Windows)
- 1(c). Node.js/NPM in the Linux instructions, on the Bash subsystem
2. Get the source code¶
Follow section “2. Get the source code” in the Linux instructions, on the Bash subsystem.
3. Set up a new database¶
Follow section “3. Set up a new database” in the Windows instructions (in Windows).
4. Install Tabbycat¶
Follow section “4. Install Tabbycat” in the Linux instructions, on the Bash subsystem.
Starting up an existing Tabbycat instance¶
To start your Tabbycat instance up again next time you use your computer:
$ cd /mnt/c/path/to/my/tabbycat/directory
$ source venv/bin/activate
$ cd tabbycat
$ waitress-serve wsgi:application
Installing Locally on Windows¶
Is this the best install method for you?
In most cases, we recommend doing an internet-based installation on Heroku instead. If you decide to do a local installation, be sure to read our page on local installations to help you understand what’s going on, particularly this section: Should I use a local installation?
If you just want to quickly set up a copy of Tabbycat to run locally on Windows, we recommend installing using Docker, which is much easier than the process below.
If you have Windows 10 and any experience with Linux, consider installing it on Bash for Windows instead, which is much easier than the process below, provided that you have experience with Linux.
Requisite technical background¶
You need to be familiar with command-line interfaces to get through this comfortably. While a background in the specific tools (Python, etc.) we use will make things easier for you, it’s not necessary: we’ll talk you through the rest. You just need to be prepared to bear with us. It’ll take a while the first time, but it gets easier after that.
In these instructions, we’ll use Windows PowerShell, a command-line interface that comes with every installation of Windows (since XP). The easiest way to find it (on Windows 7 and later) is to search for it in your Start Menu. Every line in the instructions that begins with >
is a command that you need to run in PowerShell, but without the >
: that sign is a convention used in instructions to make it clear that it is a command you need to run.
Advanced users
Tabbycat is a Django project, so can be installed in any manner that Django projects can normally be installed. For example, if you prefer some SQL system other than PostgreSQL, you can use it so long as it’s Django-compatible. Just be aware that we haven’t tried it.
1. Install dependencies¶
First, you need to install all of the software on which Tabbycat depends, if you don’t already have it installed.
1(a). Python¶
Python is a popular programming language, and the language in which the core of Tabbycat is coded.
Download and install Python 3.5 from the Python website. In the installer, check the box to add Python to your PATH (see box below).
Warning
The 64-bit version of Python 3.6 currently doesn’t work with PostgreSQL 9.6, because of a bug in Python affecting win-psycopg. If you’re using 64-bit Python, you should use Python 3.5 until the Python 3.6.1 is released.
Hint
Which file should I download?
- If you have 32-bit Windows, choose the “Windows x86 executable installer”.
- If you have 64-bit Windows (and not an Itanium processor), it’s better to choose the “Windows x86-64 executable installer”.
- If you’re not sure whether you have 32-bit or 64-bit Windows, consult “About your PC” or “System Properties” in your Start Menu.
Attention
Please take note: Just after you open the installer, check the “Add Python 3.5 to PATH” box:
To check that Python is installed correctly, open Windows PowerShell, type python
and press Enter. It should look something like this. If you installed the 32-bit version, it will say 32 bit
instead of 64 bit
.
(To exit Python, type exit()
then press Enter.)
Note
If you already have Python, great! Some things to double-check:
- You must have at least Python 3.4. (Python 2 is not supported.)
- Your installation path must not have any spaces in it.
- If that doesn’t work, note that the following must be part of your
PATH
environment variable:C:\Python35;C:\Python35\Scripts
(or as appropriate for your installation directory). Follow the instructions here to add this to your path.
1(b). PostgreSQL¶
PostgreSQL is a database management system.
Go to the PostgreSQL downloads page, then follow the link through to EnterpriseDB to download and install the latest version of PostgreSQL.
Tip
Once PostgreSQL is installed, the PostgreSQL service will run on your computer whenever you are using it. You might prefer to configure it so that it only runs when you want to run Tabbycat. To do this, open “Services” in your Control Panel on Windows, find the PostgreSQL service, and change its startup type to “Manual”. This will tell it not to start whenever you log in. Then, if you want to run the server (so you can use Tabbycat), you can do so from “Services” by selecting the PostgreSQL service and clicking “Start the service”.
1(c). Git¶
Git is a version control system.
We won’t use Git directly, but Node.js (which we install in the next step) requires Git to work. So, install the latest version for Windows from the Git website.
Advanced users
If you already have GitHub Desktop installed,
you might think that this would be good enough. Unfortunately, it’s
not—GitHub Desktop installs a portable version of Git. Node.js, on the other
hand, requires the git
to be in the PATH
, so it can call it directly.
The easiest (but not only) way to do this is just to install Git from the link
above.
1(d). Node.js/NPM¶
Node.js is a JavaScript runtime.
Download and run the node.js Windows Installer (.msi)
2. Get the source code¶
- Go to the page for our latest release.
- Download the zip file.
- Extract all files in it to a folder of your choice.
Advanced users
If you’ve used Git before, you might prefer to clone our GitHub repository instead. Don’t forget to check out the v1.3.1 tag or the master branch.
Even better, you might like to fork the repository first, to give yourself a little more freedom to make code changes on the fly (and potentially contribute them to the project).
3. Set up a new database¶
Hint
You can skip steps 2 and 3 if this is not your first installation. Every Tabbycat installation requires its own database, but they can use the same login role if you like.
- Open the pgAdmin tool, which you installed as part of installing PostgreSQL. In the object browser on the left, double-click the server marked “(localhost:5432)”. Log in using the password you set during installation.
- Right-click Login Roles, and click “New Login Role…”
Fill in the New Login Role box as follows (everything not listed below can be left as-is):
- In the Properties tab, in Role Name, choose a user account name. (If you don’t know what to pick, we suggest “tabbycat”.)
- In the Definition tab, choose a Password and type it in Password (again).
Then click OK. (Remember this user name and password, you’ll need it later.)
Right-click Databases, and click “New Database…”
Fill in the New Database box as follows (everything not listed below can be left as-is):
- In the Properties tab, in Name, choose a database name (with no spaces in it).
- In the Properties tab, in Owner, type the name of the login role you just created.
Then click OK. (Remember the database name, you’ll need it later.)
4. Install Tabbycat¶
Almost there!
Open a Windows PowerShell. Navigate to the folder where you cloned/extracted Tabbycat. For example, if you installed it in
C:\Users\myusername\Documents\GitHub\tabbycat
, then run:> Set-Location C:\Users\myusername\Documents\GitHub\tabbycat
Make a copy of local_settings.example and rename it to local_settings.py. Open your new local_settings.py. Find this part, and fill in the blanks (the empty quotation marks) as indicated:
DATABASES = { 'default': { 'ENGINE' : 'django.db.backends.postgresql_psycopg2', 'NAME' : '', # put your PostgreSQL database's name in here 'USER' : '', # put your PostgreSQL login role's user name in here 'PASSWORD': '', # put your PostgreSQL login role's password in here 'HOST': 'localhost', 'PORT': '5432', } }
Start a new virtual environment. We suggest the name venv, though it can be any name you like:
> python -m venv venv
Run the Activate.ps1 script. This puts you “into” the virtual environment:
> .\venv\Scripts\Activate.ps1
Attention
If you get an error message saying that the script isn’t digitally signed, open a PowerShell with administrator privileges by right-clicking PowerShell in the Start meny and clicking “Run as administrator”. Then run this command:
> Set-ExecutionPolicy RemoteSignedRead the warning message, then type
y
to confirm. By default, the execution policy on Windows isRestricted
, which does not permit scripts likeactivate
to be run. Changing it toRemoteSigned
relaxes it to allow local scripts to be run without checking the signature.
- Install Tabbycat’s requirements.
If you installed 32-bit Python:
> python -m pip install --upgrade pip > easy_install http://www.stickpeople.com/projects/python/win-psycopg/2.6.1/psycopg2-2.6.1.win32-py3.5.exe > pip install -r requirements_common.txt > npm installIf you installed 64-bit Python:
> python -m pip install --upgrade pip > easy_install http://www.stickpeople.com/projects/python/win-psycopg/2.6.1/psycopg2-2.6.1.win-amd64-py3.5.exe > pip install -r requirements_common.txt > npm installIf you’re using a version of Python other than 3.5, replace the URL in the second line with the appropriate link from the win-psycopg page.
Note
The second line above is an extra step just for Windows. It installs the Windows version of
psycopg2
, win-psycopg, and must be done beforepip install -r requirements_common.txt
so that the latter doesn’t try to install the Unix version.Hint
You might be wondering: I thought I already installed the requirements. Why am I installing more? And the answer is: Before, you were installing the requirements to create a Python virtual environment for Tabbycat to live in. Now, you’re in the virtual environment, and you’re installing everything required for Tabbycat to operate.
Initialize the database and create a user account for yourself:
> cd tabbycat > dj migrate > npm run gulp build > dj collectstatic > dj createsuperuser
Start Tabbycat!
> waitress-serve wsgi:applicationIt should show something like this:
serving on http://0.0.0.0:8080
- Open your browser and go to the URL printed above. (In the above example, it’s http://0.0.0.0:8080/.) It should look something like this:
If it does, great! You’ve successfully installed Tabbycat.
Naturally, your database is currently empty, so proceed to importing initial data.
Starting up an existing Tabbycat instance¶
To start your Tabbycat instance up again next time you use your computer, open a PowerShell and:
> Set-Location C:\Users\myusername\Documents\GitHub\tabbycat # or wherever your installation is
> .\venv\Scripts\activate
> cd tabbycat
> waitress-serve wsgi:application
Importing Initial Data¶
Once you’ve got Tabbycat installed, the next step is to import data for the tournament: that is, import details of teams, speakers, adjudicators and rounds. There are a few ways to do this, each with their advantages and disadvantages.
To help you decide which to choose, here’s a summary:
Method | Best for | Drawcard | Drawback |
---|---|---|---|
Demonstration data | Trying out Tabbycat | Loads sample data in one click | Not for use with real tournaments |
Simple importer | Small and medium-sized tournaments | Easy to use | Only deals with basic data |
Edit database | Adding data not handled by the simple importer or editing existing data | Can handle all types of information | Adding large amounts of data is time consuming |
importtournament
command |
Large tournaments | Easier to repeat, can handle most formats of information | Requires basic knowledge of how to use a command line interface |
Developing your own importer | Large tournaments with custom needs | Easier to repeat, will take information in whatever format it is already in | Requires background in Python and and learning about the importer classes |
Demonstration data¶
If you’re just learning or experimenting with Tabbycat, there are two demonstration datasets available, each with a sample set of teams, adjudicators, etc., so that you can immediately start running rounds. Just be aware that these probably won’t relate to anyone at your real-life tournament.
To load a demonstration dataset, click New Tournament link on the home page (once logged in as admin). You’ll see a page titled “Create New Tournament”. Scroll to the bottom of this page and click on one of the links at the bottom.
Simple importer¶
The simple importer is the easiest way to get a tournament going, and we recommend it for small- and medium-sized tournaments. It allows you to add institutions, teams, adjudicators, venues, venue categories and venue constraints. (If you need to add anything else, use the Edit Database area instead.)
To get started, create a new tournament using the New Tournament link on the home page (once logged in as admin). It’ll ask you for a few basic pieces of information.
Then, once you’re in your tournament, click Setup in the left-hand menu, then Import Data, to open the simple importer.
You first need to add institutions. Once institutions are added, you can then add teams and adjudicators in the relevant sections. Each of these is a two-step process:
- For institutions and venues, it will first ask you to copy-paste a list of names and properties in a comma-separated table format. The second step is to confirm individual fiels.
- For teams and adjudicators, it will first ask you how many teams/adjudicators to add for each institution. The second step is to fill in their details, for example, names.
Finally, if you would like to use venue categories and/or venue constraints, you can do so using the two last sections of the simple importer.
Note
If copying and pasting from a spreadsheet, an easy way to make a comma-separated table is to save a spreadsheet with the relevant information as a *.csv file, then open this file in a plain text editor (such as Notepad or TextEdit), and copying it from there.
Editing the database¶
Sometimes, the simple importer just isn’t enough—whether because you need more customization than the simple importer handles (e.g. adjudicator feedback questions), or because some participants changed their details after you imported the inital data. In this case, the easiest thing to do is to edit the database via the Django administrative interface (under Setup > Edit Database).
The general pattern goes like this: Go to Setup > Edit Database, find the type of object you wish to add/change, and click “Add” or “Change”. Then, fill in what you need to and save the object.
Caution
The Edit Database area is very powerful, and naturally if you mess things up, you can insert potentially catastrophic inconsistencies into the database. For participant information this is hard to do, but it’s worth keeping in mind.
The importtournament
command¶
We’ve written a management command called importtournament
to help automate the tournament set-up. The script, however, is neither foolproof nor comprehensive, so you might find you need to modify things slightly if your tournament structure is different from ours. Be prepared to try this a few times to get it to work. Nonetheless, this is probably the fastest way to set up a tournament.
- Copy and rename the
data/demo
folder - See the CSV files in the new folder, and add/replace the data as per your tournament. Note that the institutions (i.e. first column) in the
speakers.csv
andadjudicators.csv
files must match the institutions in the second column of theinstitutions.csv
file. And that all CSV files must end with a blank line. - Use this command, replacing
YOUR_DATA_DIR
with your new folder’s name. (Square brackets indicate optional arguments; if you use them, omit the square brackets. All of them relate to the name of your tournament.)
$ ./manage.py importtournament YOUR_DATA_DIR [--slug SLUG] [--short-name SHORT_NAME] [--name FULL_NAME]
This script has a number of options. They’re worth taking a look at before you run the script. For details, see:
$ ./manage.py importtournament --help
- Assuming the command completes successfully without errors, you should double check the data in the Django interface, as described above in Editing the database. In particular you should check that the Rounds have the correct draw types and that silent rounds have been marked correctly.
importtournament
on Heroku installs¶
The importtournament
script can be run on Heroku directly; you just need to commit and push your new data directory to your server first. See Installing on Heroku for details. If you have a local installation ready, you might like to iron out all the errors in your data until you can import locally without error, before pushing your data files to your server to be imported there.
If you want to import locally and push the database to the server, you can use the heroku pg:push
command. We assume that, if you want to use this method, you know what you’re doing or are comfortable reading the Heroku documentation to find out. We’re happy to help if you have questions about this, but for most tournaments, committing the data to the server and running the script on the server directly will be easier.
Developing your own importer¶
If our suggested file formats cause you headaches, it might be easier to write your own importer. We have a generic importer framework that should make this easier, so for some tournaments it might (very conceivably) be faster to write your own importer to conform to your data, than it is to make your data conform to our importer. You need a background in Python in order to do this. For more details, see Tournament Data Importers.
Starting a Tournament¶
This page outlines a few things you should do at the start of a tournament, after you’ve imported the initial data. Once you’ve done these, proceed to running a tournament.
Caution
Tabbycat is developed for — and tested on — modern web browsers. If you are using Internet Explorer versions 8, 7, or 6 the interface may look odd or not function properly. Switch to a newer browser if possible.
Tournament configuration¶
After importing all your data you can log into the site as an administrator by loading up the homepage and then using the Login button in the lower-right. From there you should go to the administration section of your tournament, and then go to the tournament configuration page by clicking Setup then Configuration in the menu.
Here you can adjust the debate rules and interface options to your liking then hit Save when finished. We also offer a number of presets that apply particular rule sets (such as the Australs rules) or feature sets (such as displaying information normally released during briefs on the website).
Special data types and options¶
There are a few optional fields that are not covered in the initial data templates, in the visual importer, or that may only be relevant in particular scenarios. It’s worth going over these quickly to see if they are needed for your tournament. You can view and edit these fields in the Edit Database area (link is in the menu under Setup).
- Adjudicator Feedback > Adj Feedback Questions
- As described in Adjudicator Feedback, the types of questions that can be posed for adjudicator feedback are able to be heavily customised. If you are customising your feedback form it should be done here, and before the tournament starts.
- Authentication and Authorisation > Users
- Here you can add new admin users (those with full access) as well as new assistant users those (who can only do common data-entry tasks but not edit or view the full tab interface). See User Accounts for information on how to do this.
Note
The people you’re adding accounts for should be physically present when you do this, so that they can enter their password.
- Participants > Regions
- Optionally, each institution may belong to a Region. An institution’s region is used within the adjudicator allocation process to visually identify teams and adjudicators for the purposes of highlighting diversity issues. These have traditionally been used for geographic regions (such as Oceania), although could be repurposed as arbitrary markers of information — for example they could be used to denote teams from a particular State, institutional size, or circuit.
- Participants > Adjudicators
- An adjudicators Test Score represents their relative ability to judge important rooms, where adjudicators with higher numbers will, relative to the other adjudicators, be placed in better roles (ie as Chairs) and in the rooms you deem most important in each round. If you are running a small tournament, and plan to do your allocations manually, you can set everyone’s number to the same amount.
- For larger tournaments, particularly those that collect feedback, see the Adjudicator Feedback section for more information on how test scores and other variables influence the automated allocation process.
- Regardless of how you score the adjs, if you have changed the minimimum chairing score in settings, you’ll want to make sure there are enough adjudicators that meet this minimum threshold or the automated allocator may not function effectively.
- All types of conflicts are assigned to the relevant adjudicator. Adjudicator’s can be conflicted against particular teams, particular institutions, and other adjudicators. Each of these is a located in a tab at the top of the page.
- Each adjudicator’s gender is optional and is not displayed publicly; it is only shown in the adjudicator allocation interface
- Each adjudicator’s pronoun is optional, and is only displayed if you use tabbycat to print the ballots and feedback sheets for each round.
- Participants > Teams
- Note the distinction here between full name and short name. The latter is used on pages where space is tight, such as the draw displays or the adjudicator allocation interface.
- Note that “Uses institutional prefix” option. With this option on, a team from the ‘MUDS’ insttution named ‘1’ or ‘Gold’ would be displayed as ‘MUDS 1’ or ‘MUDS Gold’.
- At present, setting a team’s type to Bye, Swing, or Composite only affects very particular circumstances, and should be considered unnecessary.
- If you do have composite teams, and wish to have them be conflicted by adjudicators from each respective instutution, you’ll need to add a new team conflict to each adjudicator from each institution.
- If you do have swing teams, or teams that are otherwise ineligible for breaking, this is typically handled through the breaks interface in the main site
- Participants > Speakers
- Each speaker’s gender is optional and is not displayed publicly; it is only shown in the adjudicator allocation interface
- Each speaker’s pronoun is optional, and is only displayed if you use tabbycat to print the ballots and feedback sheets for each round.
- Tournaments > Divisions
- At the moment divisions are only useful for running tournaments that use round-robin style draws. Here, each division represents a draw pool within a round. Division support here is under development and not tested in many scenarios.
- Tournaments > Tournaments
- Note that tournaments can have a welcome message (useful for displaying maps and other information on the homepage).
- Venues > Venues
- A venue’s priority determines its priority in being allocated. If there are 20 debates, and 30 rooms, the 20 rooms with the highest priorities will be chosen. Furthermore, if particular debates are marked as important during the draw process, those debates will receive the rooms with the highest priorities. In this way you can give close rooms to members of the adj core, or give larger rooms to debates that will draw a large audience.
- Venues > Venue Categories
- Venue categories are not needed for most kinds of tournaments. Their purpose is to classify particular venues, such as venues all within one building or venues that are accessible. Once assigned these categories can display in the venue’s name — ie “Red 01.01” or be used to assign Venue Constraints that match particular teams, institutions, or adjudicators to particular types of venues.
Information for the briefing¶
If you’re using the online submissions feature, some things you should probably mention in the briefing:
- Adjudicators must fill out ballots completely, including motions and venues—they are entered into the system.
- There is a static URL for each person’s ballots and feedback forms. It can be bookmarked, or the page can refreshed after each round.
- If people submit a result or feedback online, they should indicate that they have done so on the paper copy of their ballot.
Running a Tournament¶
Once you’ve finished the steps in Starting a Tournament, you’re ready to go! This page outlines what you would do for each round during the tournament. After the tournament, proceed to Finishing a Tournament.
This is all done from an admin interface (i.e., by the tab director or adjudication core member). In the admin interface, tournament-wide pages (feedback, standings, and break) are at the top of the left-hand menu, while round-specific pages (check-ins, draw, display, motions, and results) are in dropdown’s organised by each round;s abbreviation.
The basic workflow for each round is:
- Check-in the teams, adjudicators, and venues present
- Generate the draw and allocate the adjudicators
- Show/release the draw
- Release/enter the motions
- Have the debates
- Enter results
- Advance to the next round
Check-ins¶
Set availability. For each round, you need to set the venue, team and adjudicator availability. If any of those are not marked as available they will not be used within the draw; so this feature is mostly useful for when adjudicators or venues are only available for certain rounds.
To do this, click the round in the menu, then click Check-Ins. Here you can then go to the availability pages for venue, teams, and adjudicators, or check in everything at once. When you’ve set everything appropriately use the Generate Draw button in the top right to advance.
Note
You can set availabilities in advance of the current round — ie if you know the venue/adjudicator schedules their availabilities can be set ahead of time.
Generating the draw¶
- Confirm the draft draw. After advancing from availability section you will first be shown a draft draw that details how the draw was formulated, pointing out pull-ups and conflict swaps and the like.
Note
The draft draw is for you to double-check. While there are some basic tests on the draw algorithm, it never hurts to sanity-check it again.
If you do find something wrong with a draft draw, you can edit the match-ups, but please also let us know what the problem was! You can find our contact details in the Authors section.
- Once on the confirmed draw page you can click Edit Adjudicators.
- Allocate the adjudicators. Changes here will auto-save; feel free to return to the Draw when needed. See adjudicator allocation for more details about the allocation process.
Note
If you are using venue constraints the Draw page may prompt you to Auto Allocate the venues used to satisfy those constraints; see venue-constraints for more details. Regardless of whether you are using venue constraints or not you can change the Venues per-debate in the Edit Venues area.
Releasing the draw¶
Once you’re happy with your adjudicator allocation, you’re ready to start the round.
- Release to general assembly. From the Display page for that round, go to Show by Venue or Show by Team (whichever you prefer). Then put it up on the projector. There are automatic scroll buttons and buttons for changing text sizing.
- Release to public. If you’re using the public draw function (where the draw is posted publicly to your Tabbycat website) use the Release to Public button to allow the page to display.
Tip
To avoid the site from being overloaded by anxious refreshers, we recommend that large tournaments not release the draw to the public until after it’s been seen by general assembly.
Entering and Releasing Motions¶
Tabbycat is agnostic as to whether you enter motions into Tabbycat before or after they are shown publicly. However, they must be entered at some point before ballots are entered.
- Enter the motion text. Either before or after their public release motions can be entered in the Motions section for that round.
- Release to general assembly. If you are entering motions before they are publicly revealed note that there is a Display Motions button in the Display area that allows you to do a Power Point style motion release.
- Release to public. As with draws, if you have the enable public view of motions setting configured your Tabbycat website will display a running list of motions from the tournament. When this is on, using the Release Motions to Public button on the Motions page will mark the current set of motions as able to be displayed on this page.
Entering Results¶
- Enter debate results and feedback as they come in (and/or allow online entry of results and feedback).
- Both results and feedback entered in the tab room or online need to be confirmed before the results are counted. To confirm a debate ballot and the debate as a whole, the confirmed checkbox under Ballot Status should be ticket in addition to the Debate Status being set to Confirmed.
- Note that you can track data entry progress from the Overview page in an admin account (get there by clicking the tournament’s name in the menu).
See Entering Ballots and Feedback for more details about the data entry process.
Warning
For major tournaments, we don’t recommend entering any data from an admin’s account. This is because the admin interface (intentionally) does not enforce the data confirmation procedure.
Advancing to the next round¶
Once you’ve got all the results entered and confirmed, you’re ready to progress to the next round. This can be done by going to the Results area, and then using the Advance to Next Round button.
Warning
When you advance to the next round, if you’ve enabled public results, the results for the current round (which is now the previous round) will be release to the public unless the round is marked as “silent” in the database. So if you’re careful about when results should be released, don’t change the current round until you’re ready to release those results.
Note
There is a design assumption that you will always want to release results for non-silent rounds before you start working on the draw for the next round. If this isn’t true for you, please get in touch with us so that we know. The workaround is to make all rounds silent, then unsilent them when you’re ready to release results.
Finishing a Tournament¶
This page outlines some final steps to take after the conclusion of outrounds.
Tab Release¶
Tabs can be released using the Tab released option under Setup > Configuration. Tabbycat offers a Team Tab, Speakers Tab, Pros Tab, Novices Tab, Replies Tab, and Motions Tab that can be each released independently. Additionally, you can limit each of these tabs to only show a set number of speakers, i.e. only release a “Top 10 Speakers” tab.
There is also the option to redact individual speaker’s identifying details (name, team, and institution) from the public individual tabs. You can do so by going into the Edit Database area, going to Participants > Speakers, finding the speaker and clicking the Anonymous box (and saving).
Note
Public tab pages are cached for performance reasons. This means that any changes that affect a tab page (say redacting a speaker or changing a speaker score) may not show up on the public site for up to an hour.
Wrapping Up¶
You probably want to turn off the Public ballots, Public feedback, Feedback progress, and Public draw features under Configuration at this stage as they no longer have any use.
You also want to go into the Edit Database area, find the tournament and hit “release all” so that the results for the final round can be released.
Adjudicator Feedback¶
You can set the questions that are used on adjudicator feedback forms. The only field that is permanently there is the score
field, which is an overall score assessing the adjudicator. All other questions (including a generic comments section) must be defined if you want them to be on the form.
Currently, there are two methods of setting questions:
- through the edit database area. Go to Setup > Edit Database, then click Change next to Adjudicator feedback questions. You can add questions here.
- using the importtournament command.
Most of what you need to know is explained in help text in the edit database area. (Even if you’re using importtournament
, you might find the field
descriptions in the edit database area helpful.) Some more details are here.
Answer types and options¶
Type | Relevant options | Appearance |
---|---|---|
checkbox | - | |
yes/no (dropdown) | - | |
integer (textbox) | min_value, max_value | |
integer scale | min_value, max_value | |
float | min_value, max_value | |
text | - | |
long text | - | |
select one | choices | |
select multiple | choices |
Options:
min_value and max_value specify the minimum and maximum allowable values in the field. Mandatory for “integer scale” types and optional for “integer (textbox)” and “float” types.
choices is used with “select one” and “select multiple” types, and is a
//
-delimited list of possible answers, e.g.biased//clear//concise//rambly//attentive//inattentive
required specifies whether users must fill out the field before clicking “submit”. This requirement is only enforced on public submission forms. It is not enforced on forms entered by tab room assistants.
The exception to this is the “checkbox” type. For checkboxes, “required” means that the user cannot submit the form unless the box is checked. Think of it like an “I agree to the terms” checkbox. This isn’t a deliberate design decision—it’s just a quirk of how checkboxes work on web forms.
Want another answer type?¶
We don’t really intend to add any further complexity to the built-in feedback system. If the above answer types don’t cover your needs, we suggest using a third-party feedback system. You might be able to adapt SurveyMonkey, Google Forms or Qualtrics to your needs.
We may be persuaded to make an exception if the new question type you have in mind is easy to add: that is, if it is straightforward to implement using standard web page elements and fits into the existing questionnaire framework (see Different questionnaires below). If you think there is such a case, please contact us using the contact details in the Authors section.
Different questionnaires¶
Tabbycat allows you to specify two questionnaires: one for feedback submitted by teams, and one for feedback submitted by adjudicators. You must specify in each question whether to include the question in each questionnaire.
- from_team, if checked, includes the question in feedback submitted by teams
- from_adj, if checked, includes the question in feedback submitted by adjudicators
Who gives feedback on whom?¶
Tabbycat allows for three choices for which adjudicators give feedback on which other adjudicators:
- Chairs give feedback on panellists and trainees
- Chairs give feedback on panellists and trainees, and panellists give feedback on chairs
- All adjudicators, including trainees, give feedback on all other adjudicators they have adjudicated with
You can set this in the feedback paths option under Setup > Configuration > Feedback. Your choice affects each of the following:
- The options presented to adjudicators in the online feedback form
- The printable feedback forms
- The submissions expected when calculating feedback progress and highlighting missing feedback
The feedback paths option only affects feedback from adjudicators. Teams are always assumed to give feedback on the orallist, and they are encouraged to do so through hints on the online and printable feedback forms, but there is nothing technically preventing them from submitting feedback from any adjudicator on their panel.
Advanced users
If you need a different setting, you need to edit the source code.
Specifically, you should edit the function expected_feedback_targets
in
tabbycat/adjfeedback/utils.py.
Unless we can be convinced that they are very common, we don’t intend to add any further choices to the feedback paths option. If your needs are specific enough that you need to differ from the available settings, they are probably also beyond what is sensible for a built-in feedback system, and we recommend using a third-party feedback system instead.
How is an adjudicator’s score determined?¶
For the purpose of the automated allocation, an adjudicator’s overall score is a function of their test score, the current round’s feedback weight, and their average feedback score. This number is calculated according to the following formula:
where is the feedback weight for the round.
Under this formula, each round’s feedback weight can be used to determine the relative influence of the test score vs feedback in determining the overall score. As an example, say that an adjudicator received 5.0 as their test score, but their average feedback rating has thus far been 2.0. If the current rounds’ feedback weight is set to 0.75, then their overall score would be 2.75. If the current round’s feedback weight is set to 0.5 their score would be 3.5. If the weight was 0, their score will always be their test score; if the weight was 1 it will always be their average feedback value.
It is common to set rounds with a low feedback weight value early on in the tournament (when feedback is scant) and to increase the feedback weight as the tournament progresses.
Note
A participant’s test score can, in conjunction with feedback weight, also be used as a manual override for an adjudicator’s overall ranking. At several tournaments, adjudication cores have set every round’s feedback weight to 0, and manually adjusted an adjudicator’s test score in response to feedback they have received and reviewed. In this way complete control over every adjudicator’s overall score can be exerted.
Note
If feedback from trainee adjudicators is enabled, any scores that they submit in their feedback are not counted towards that adjudicator’s overall score.
Adjudicator Allocation¶
The adjudicator allocation screen offers the ability to automatically generate an allocation and/or allow you to create an edit an allocation manually.
Creating an automatic allocation is as simple as hitting the Auto Allocate button. Before you do so however, you may want to change the ‘importance’ value of the debates — as defined in the column with the fire symbol. Debates with a higher importance value will receive a stronger panel.
Adjudicators can be dragged into position, or into the Unused section on the right. Dragging an adjudicator into the chair position, when an adjudicator is already there, will swap the pair.
Various kinds of information are displayed using different colour codes. When hovering over, or dragging an adjudicator:
- Their conflicts with other adjudicators and teams will show as red highlights
- Their institutional conflicts with other adjudicators and teams will show as orange highlights
- Teams and adjudicators they have previously seen will highlight blue.
These colors are also used when adjudicators are in positions where any of the above apply. IE, in a panel where the team and adjudicator are conflicted, each will be highlighted red. In addition, panels with odd numbers of adjudicators, or that are missing a chair will be highlighted purple.
In addition, if you have importer gender, regional, and/or assigned multiple break categories to the teams, you can turn on the toggles that display this information in the draw (it will also display a color key).
Backups¶
The backup utility isn’t part of Tabbycat. Heroku provides a very good backup utility for all sites hosted on Heroku, and for Heroku-based Tabbycat sites, we strongly recommend it.
You should always back up the database before deleting any data while in the Edit Database area, because deleting data cannot be undone. It is also a good idea to back up the database before doing anything in the Edit Database area, unless you’re very familiar and confident with editing the Tabbycat database directly.
You may, as a matter of standard practice at large tournaments, wish to back up the database twice per round: Once just after you’ve generated the draw and allocated adjudicators, and once just after you’ve finished entering results.
Installations on Heroku¶
Heroku provides a utility to easily back up and restore the entire site database.
If you don’t have the Heroku CLI¶
You can capture backups from the Heroku Dashboard:
- Go to the Heroku Dashboard and click on your app.
- Under Installed add-ons, go to Heroku Postgres.
- Scroll down, and click on the Capture Backup button.
You can’t restore a backup without the Heroku Command Line Interface (CLI), so if you end up needing your backup, you’ll need to install the Heroku CLI, and then follow the instructions below.
If you have the Heroku CLI¶
The best guide to backing up databases is the Heroku Dev Center’s PGBackups guide.
To capture a backup:
$ heroku pg:backups:capture
To restore a backup:
$ heroku pg:backups:restore
If you have multiple Tabbycat sites, you’ll need to specify which one by adding
--app mytournamentname
to the end of the command.
Local installations¶
There are lots of ways to back up local PostgreSQL databases, but we’d suggest using the pg_dump and pg_restore commands.
Breaks and Break Rounds¶
In Tabbycat, elimination rounds (sometimes called outrounds or the final series) are called “break rounds”, and the qualification of teams to compete in the elimination phase of a tournament is called the “break”.
About break categories¶
Tabbycat supports multiple and arbitrarily-named break categories. Most tournaments will have just one category, typically called “Open”, leading to the grand final. Some tournaments also have restricted-eligibility break categories, for example, for novice teams or teams for whom English is a second language.
Having multiple break categories is intended for tournaments where multiple parallel elimination phases derive from the same preliminary rounds (inrounds). It’s not for parallel but distinct competitions—for those, you should create distinct tournaments.
Break qualification rules¶
Tabbycat supports several break qualification rules, and each break category must be configured to use one of them. Most tournaments will use “Standard”, which is the default.
Rule name (string to
use in importtournament
CSV files) |
Description |
---|---|
Standard
(standard ) |
The top n teams break. This is the default, and most tournaments use this rule. |
AIDA 1996
(aida-1996 ) |
The top n teams that are also in the top three teams from their institution break. |
AIDA 2016 (Australs)
(aida-2016-australs ) |
The top n teams that fulfil either of these criteria break:
If fewer than n teams fulfil either criterion, then the best teams not fulfilling the criteria are added to make n teams. |
AIDA 2016 (Easters)
(aida-2016-easters ) |
As for AIDA 2016 (Australs), except that if fewer than n teams fulfil either criterion, then only the best teams who are in the top three teams from their institution are added to make n teams. |
WADL division winners
first
(wadl-div-first ) |
The division winners are taken first, then the best teams who did not win their division are added to make n teams. |
WADL division winners
guaranteed
(wadl-div-guaranteed ) |
The division winners are guaranteed to break, and the best teams who did not win their division are added to make n teams. (Teams are sorted in their original rankings, unlike the “division winners first” rule.) |
Note
The break generators are somewhat more complex than described in the above table: among other things, they also handle cases where there is a tie for the last place in the break, and for those break categories marked “general”, they will show where ineligible teams would have broken, had they been eligible.
Setting up break categories and rounds¶
For each break category in your tournament, you need to do three things:
- Create (and name) a break category
- Create break rounds for the category
- Set the eligibility of teams to compete in the category
If you only have one break category (open) and you create your tournament using the “Create New Tournament” page, simply enter the number of teams in the break (e.g., 8 if you’re breaking to quarterfinals). Tabbycat will create the break category and break rounds for you. You’ll still need to set the eligibility of teams though, as in (3) below. For any further break categories, you’ll need to do all three steps yourself.
If you create your tournament using the importtournament command or in Edit Database, you’ll need to do all three steps above yourself.
1. Creating break categories¶
If using the importtournament command, there is an example file, break_categories.csv, that you can copy and adjust. If using Edit Database, add categories under Break Qualification > Break categories.
Most of the fields are self-explanatory or described on the Edit Database form,
except for one: “rule”, which sets the break qualification rule. Permissible
values are described in Break qualification rules above. If using
importtournament, be sure to use the correct string (in brackets in the
table). The rule defaults to “Standard” (standard
).
Note
The “institution cap” field was removed in Tabbycat 1.0. All Australs break qualification rules are now hard-coded to a cap of three teams per institution.
2. Creating break rounds¶
You should create a round for every break round you intend to hold, including it in rounds.csv if using importtournament, or adding them under Tournaments > Rounds if using Edit Database. Be careful to set the following fields correctly:
- Break category must be set to the relevant break category.
- Stage must be set to “Elimination”.
- The first elimination round must have its draw type set to “First elimination”.
- All other elimination rounds must have their draw types set to “Subsequent elimination”.
3. Setting break eligibility¶
Once a break category has been created it will not have any teams eligible for it, even if it was marked as “Is general”. To edit the eligibility of teams for any break round go to the Breaks item in the left-hand menu for a particular tournament and then click Edit Eligiblity.
Here you can select “all” or “none” to toggle all team eligiblities or edit them using the tick boxes. Once you save it should return you to the main break page which will display the number of teams marked eligible.
Note
Adjudicators can be marked as “breaking” on the Feedback page; clicking Adjudicators on the breaks page will take you straight there.
Generating the break¶
Unlike team or speaker standings, each category’s break (and the break ranks of teams) are not determined automatically and updated continuously. Instead each can be generated (and regenerated) as desired.
To do so go to the Breaks item in the left-hand menu and then click the white button that corresponds to the break category you’d like to determine the rankings for. When prompted, select Generate the break for all categories to display the list of breaking teams.
From this page you can update the breaking teams list for this break category (or all categories) as well as view and edit ‘remarks’ that account for cases in which a team may not break (such as being capped or losing a coin toss).
Caution
Please double-check the generated break before announcing or releasing it. Although the break generation code is designed to handle edge cases, we don’t test the code for such cases.
Creating draws for break rounds¶
Creating a draw for a break round proceeds as normal, except that the team check-in process is skipped. Instead, when you visit the check-ins page for that round it will have automatically determined which teams should be debating based upon the determined break for that category. Once a draw has been generated it will then use the relevant break ranks to create the matchups (ie 1st-breaking vs 16th-breaking, 2nd vs 15th, etc.). Subsequent break rounds will then also automatically determine matchups based on the previous round’s results and the initial break ranks of each team.
If the “break size” of a break category is not a power of 2, it will treat the first break round as a partial-elimination draw and only create a draw for the teams not skipping the partial-elimination round. Subsequent break rounds will then process as described above.
Entering Ballots and Feedback¶
Ballot check-in¶
For tournaments that require it, there is a “ballot check-in” page that can be used to record the arrival of ballots to the tab room. When there’s a missing ballot, it can help establish whether the ballot never made it to the tab room, or whether it’s probably floating around in the room forgotten. Also, it can help enforce early checks that panels return the correct number of ballots to the room.
To get to the ballot check-in, click the relevant round in the menu of the admin interface, and then click “Results” and then “Ballot Check-In”. This requires superuser privileges.
There’s no adverse effect from not using the ballot check-in. Data enterers will still be able to enter and confirmed ballots, even if not checked in.
Tip
- Since the ballot check-in tends to require a dedicated computer or two, it can be worth creating a separate superuser account for ballot check-in, so that it doesn’t appear on the action logs as being by a particular person.
- Don’t forget to provision a computer or two for this if you’re planning to use it.
- Ballot check-ins can be a bottleneck, so you might decide they’re not worth using. Alternatively, you might have multiple computers for this purpose, or you might dedicate a tab room helper to driving the process (since this is probably faster than runners doing the typing in turn).
Ballot entry¶
Most tab rooms run some sort of check system to ensure data is entered accurately. In Tabbycat, this is built into the system, which also helps speed it up.
As a general principle, Tabbycat requires all ballots to be looked at by two people. The first person enters the data from the ballot, and the second person checks it. The second person isn’t allowed to modify the data—they either confirm it or reject it, and if they reject it, then the whole process starts again. This is by design: to be confirmed, the same data must have been seen by at least two people.
Caution
The Tabbycat admin interface does not work like this. It’s designed to be flexible, so allows you to edit, confirm or unconfirm any ballot at any time. For this reason, you should not use the Tabbycat admin interface for general data entry. If a tab director or adjudication core member will be entering data, they should have a separate account for this purpose.
Tip
- Don’t forget to check the totals against the ballot—they’re a useful integrity check too.
- Don’t forget to check the winner against the ballot! If the adjudicator gets it wrong, it’s worth asking to clarify.
- It can be helpful to think about the room layout to maximize efficiency.
- Some tab rooms like to assign some to data entry and some to verification. This isn’t really necessary, since Tabbycat doesn’t let the same person enter and verify the same ballot. (This is one of many reasons why every person should have their own account.)
Duplicate/Swing Speeches¶
When entering the ballots there is a toggle label ‘Iron’ speeches. When set to “yes” this allows you to have the same speaker deliver multiple speeches provided their extra speeches are labelled on the form as ‘duplicates’. Typically, most tournaments require that lesser ‘iron man’ speech is discarded from the tab, which would mean that you would mark the lower speaker of the two scores as the duplicate (note that this may require you to check each score’s average across a panel).
Speeches marked as duplicates are not included in the speaker tab. This means that they can also be used to exclude swing speakers from the tab as needed; even if they do not actually speak twice. To do so, change the name of the swing speaker to be that of an existing team member and ensure that that speech is marked as a duplicate.
Tip
There is also an option under Standings in the Configuration section that specifies the number of debates a speaker can miss before you will not show on the tab. By default it is set to 1, but if need be this can be increased to hide swing speakers from the final speaker tab.
Feedback entry¶
Feedback doesn’t have the same verification process as ballots. Feedback that is entered by the tab room is assumed to be confirmed. If feedback is entered multiple times, all copies are retained but only the last one “counts” (is considered confirmed).
Online entry¶
There are two methods of allowing ballots and feedback to be submitted online. Both are set in the Data Entry page of each tournament’s Configuration section and can be set independently; both in whether each can be submitted online at all and in which method of online submission are available.
Private URLs¶
The first method of data entry is using ‘private URLs’. When this setting is enabled you can create a special URL that is unique to a particular team or adjudicator. This link contains a number of random characters and is not displayed publicly; it is in effect a secret that only that particular participant should know. Presuming people do not share these links to others this provides a means to (relatively) securely identify who is submitting what information. Because Tabbycat knows which team or adjudicator has which URL it will only allow them to submit feedback/ballots for debates that they were speakers/adjudicators in.
Warning
Private URLs should provide more than adequate security for almost all tournaments’ purposes, but they aren’t foolproof. Anyone with access to the URL for a participant can submit feedback from them, so it’s important that participants not share their URLs. This also means participants need to be careful when submitting from devices they do not own, because the URL will be logged in that device’s browser history.
These links must be generated within Tabbycat after the preference is enabled. To do so go to the Feedback section and then the Private URLs area. Once there you will be prompted to generate those URLs for all participants, which — once generated — will be presented in separate tables (one for teams; one for adjudicators).
These URLs can then be distributed to each person in a number of ways. There are pages within Tabbycat for printing them out (one URL per page labelled by recipient) or emailing them out (providing participants have been assigned email addresses). In the past tournaments have also used data from this table to send out SMSs by bulk, or distributed them to institutional representatives to disburse.
Tip
You can assign email address to participants using the importtournament command when importing your registration data, or by going to the Edit Data area and looking up each Speaker/Adjudicator.
Tip
If, after generating the private URLs, you add additional Teams or Adjudicators you can go to the Edit Data area , look up each Speaker/Adjudicator, and type in a bunch of random characters as their Url key to assign them a private URL.
Tip
You can delete the current set of URLs by running this command in a shell on your server (replacing TOURNAMENT_SLUG with the appropriate value):
python manage.py randomisedurls delete --tournament TOURNAMENT_SLUG
Public URLs¶
The second method of data entry is using ‘normal URLs’. This essentially means that any users visiting the public version of the site is able to submit a ballot or feedback (as specified by their respective settings). They do so by self-selecting which Team or Adjudicator they are then entering in a form as normal.
This is, rather obviously, not a particularly secure method of data entry — nothing is stopping anyone on the site from entering data as someone else. The data can be checked, verified, and edited as normal by admins however. As such, this method is only recommended for small tournaments where you can trust those present to enter accurate information (or where accuracy is not crucial).
Tip
There is an additional setting to set a ‘tournament password’ that needs to be submitted to enable the form. It is imagined, that if enabled, this password would only be distributed to tournament participants. However this only helps (at best) prevent non-participants from entering information; the fundamental problem of not verifying who is submitting what information is still present.
Draw Generation¶
The draw generator is quite flexible. You can specify a number of settings to suit different tournaments’ rules.
Options¶
The options discussed here are set in the Configuration page as described in starting a tournament.
Caution
The valid options for intermediate bubbles change depending on whether sides are pre-allocated, but these are not checked for validity. If you choose an invalid combination, Tabbycat will just crash. This won’t corrupt the database, but it might be momentarily annoying.
Summary¶
Option | Description | Allowable values |
---|---|---|
Draw odd brackets | How to resolve odd brackets |
If sides are Random or Balance:
If sides are Pre-allocated:
|
Draw side allocations | How to allocate aff/neg |
|
Draw pairing method | How to pair teams within brackets |
|
Draw avoid conflicts | How to avoid history/institution conflicts |
|
Odd bracket resolution¶
The draw odd brackets option specifies what you do when a bracket has an odd number of teams. (Obviously you have to do something, otherwise you can’t pair off teams within the bracket.) There are two groups of methods: pull-up and intermediate bubbles.
- Pull-up methods take one or more teams from the next bracket down, and move them into the odd bracket to fill the bracket.
- Intermediate bubbles take the excess teams from the odd bracket and move them down into a new bubble, which sits between the odd bracket and the next one down (hence the name “intermediate”). It then takes one or more teams from the next bracket down and moves them to fill the new intermediate bubble.
The exact mechanics depend on whether or not sides are pre-allocated.
When sides are not pre-allocated¶
Pull-up methods take a team from the next bracket down, and add them to the odd bracket to form an even bracket. You might pull up the top team from the next bracket, or the bottom team, or a randomly chosen team.
Intermediate bubbles take the bottom team from the odd bracket and match them against the top team from the next bracket. An intermediate bubble always has two teams.
If you’re using conflict avoidance and intermediate bubbles, you will probably want to use Intermediate with bubble-up-bubble-down instead. This uses the “bubble-up-bubble-down” rule to swap teams out of an intermediate bubble if there is a history or institution conflict. This is defined in the Australs constitution and is analogous to the “one-up-one-down” rule.
Caution
Using Intermediate with One-up-one-down does not imply Intermediate with bubble-up-bubble-down. You must enable Intermediate with bubble-up-bubble-down specifically.
When sides are pre-allocated¶
When sides are pre-allocated, an “odd bracket” is one that has an uneven number of affirmative and negative teams. (So odd brackets can have an even number of teams, e.g. 4 affs and 2 negs.)
Pull-up methods take as many teams from the next bracket down as necessary to fill the bracket. If there aren’t enough teams in the next bracket down, it will take teams from the bracket after that, and so on, until the (original) odd bracket is filled. Higher brackets are always filled first. You might pull up the top teams from the next bracket, the bottom teams, or a random selection of teams.
Intermediate bubbles take the unpaired teams in a bracket, and move them down to a new intermediate bubble. It then takes the number of teams necessary from the opposite side, from the next bracket down, to fill the next bubble.
Intermediate 1 and Intermediate 2 differ only in what happens if there aren’t enough teams in the next bracket to fill the intermediate bubble. In Intermediate 1, it will just take teams from the bracket after that, and so on, until the intermediate bubble is filled. In Intermediate 2, it will split the intermediate bubble: the teams that can be paired with the next bracket form the first intermediate bubble, and then the teams that aren’t form a new (unfilled) intermediate bubble, to be filled from teams from the bubble after that. This keeps going, splitting into as many intermediate bubbles as necessary, until all excess teams from the original odd bracket are paired.
Side allocations¶
There are four methods:
- Random allocates randomly. Some tournaments might like this, but most will probably want to use balance, because Random doesn’t guarantee that a team won’t be (say) affirming the entire tournament.
- Balance assigns the team that has affirmed less so far the affirmative side (and, therefore, the team that has negated less the negative side). If both teams have affirmed the same number of times, it assigns sides randomly.
- Preallocated is used for pre-allocated sides. If used, you must enter data for pre-allocated sides into the database, as specified below.
- Manually enter from ballot is used for tournaments where the sides of the teams involved are not assigned in advance, but are instead determined by the teams themselves
Pre-allocated sides¶
There isn’t currently any way to edit side allocations from the front end. To do so from the back end, you need to create one TeamPositionAllocation
entry for each team in each round. All teams must have an allocation for every round. There are a few ways to do this, take your pick:
- If you’re using the importtournament command, it reads sides from the file sides.csv.
- You can do this from the Django admin interface (under Setup > Edit Database) by going to the relevant team and adding a team position allocation entry. That is:
- Click Admin on the bottom right of any page after logging into an account with superuser access.
- Next to Teams, click Change.
- Click on the name of the team you want to edit side allocations for.
- Add or edit the entry or entries in the Team position allocations table at the bottom.
- You can also do this by writing a script that creates
TeamPositionAllocation
objects and saves them. Have a look at data/utils/add_random_side_allocations.py for an example.
Pairing method¶
It’s easiest to describe these by example, using a ten-team bracket:
- Fold: 1 vs 10, 2 vs 9, 3 vs 8, 4 vs 7, 5 vs 6. (Also known as high-low pairing.)
- Slide: 1 vs 6, 2 vs 7, 3 vs 8, 4 vs 9, 5 vs 10.
- Random: paired at random within bracket.
- Adjacent: 1 vs 2, 3 vs 4, 5 vs 6, 7 vs 8, 9 vs 10. (Also known as high-high pairing.)
Teams are always paired within their brackets, after resolving odd brackets.
Conflict avoidance method¶
A conflict is when two teams would face each other that have seen each other before, or are from the same institutions. Some tournaments have a preference against allowing this if it’s avoidable within certain limits. The draw avoid conflicts option allows you to specify how.
You can turn this off by using Off. Other than this, there is currently one conflict avoidance method implemented.
The One-up-one-down method is the method specified in the Australs constitution. Broadly speaking, if there is a debate with a conflict:
- It tries to swap teams with the debate “one up” from it in the draw.
- If that doesn’t work, it tries to swap teams with the debate “one down” from it in the draw.
- If neither of those works, it accepts the original conflicted debate.
It’s a bit more complicated than that, for two reasons:
- History conflicts are prioritised over (i.e., “worse than”) institution conflicts. So it’s fine to resolve a history conflict by creating an institution conflict, but not the vice versa.
- Each swap obviously affects the debates around it, so it’s not legal to have two adjacent swaps. (Otherwise, in theory, a team could “one down” all the way to the bottom of the draw!) So there is an optimization algorithm that finds the best combination of swaps, i.e. the one that minimises conflict, and if there are two profiles that have the same least conflict, then it chooses the one with fewer swaps.
Known tournaments draw options¶
The settings that should be used for some tournaments are as follows:
Tournament | Setting | Suggested value |
---|---|---|
Australs | Odd brackets | Intermediate with bubble-up-bubble-down or Pull up from top |
Side resolution | Balance | |
Pairing method | Slide | |
Avoid conflicts | One-up-one-down | |
Joynt Scroll | Odd brackets | Intermediate 1 or Intermediate 2 |
Side resolution | Pre-allocated | |
Pairing method | Fold | |
Avoid conflicts | Off |
What do I do if the draw looks wrong?¶
You can edit match-ups directly from the draw page. Technically, you can do anything you want. Of course, operationally, you should only edit the draw when you know that the draw algorithm got something wrong. If you need to do this, even just once, please file a bug report by creating a new issue on our issues page on GitHub.
Technical notes¶
Note
The information in this section should be read in conjunction with the source code documentation.
The draw module is based around DrawGenerator
, a factory function that returns a subclass of BaseDrawGenerator
. DrawGenerator
takes two mandatory arguments: draw_type
, a string, and teams
, a list of Team
-like objects.
As a design principle, the draw module does not rely on internal knowledge of models.py
. Rather, to enforce abstraction and to ease unit testing, it is written as a stand-alone module that could, in principle, be used by other applications. Therefore, it defines an interface and uses duck-typing to work with inputs.
Team
-like objects are the main part of this interface. The draw module doesn’t provide a base object for Team
-like objects, nor does it expect them to be a Django model or be called Team
. Rather, it merely expects Team
-like objects to have certain attributes, depending on the options passed to DrawGenerator
. For example, for power-paired draws, Team
-like objects must have the points
attribute. (For further details, refer to the source code.) Because DrawGenerator
returns the same objects in some methods, Team
-like objects must be hashable.
The make_draw()
method returns a list of Pairing
objects. The Pairing
class is defined in the draw module. Its teams
attribute (and all attributes derived from it) contain the same Team
-like objects that were passed to DrawGenerator
.
Printing Ballots and Feedback¶
Tabbycat offers the ability to print scoresheets and feedback sheets on a per-round basis. This means that each scoresheet is customised to match the draw, and so will display:
- The motion or possible motions that could have been chosen from
- The teams, and a list of speakers for each team
- The room number, and name of the adjudicators present
Feedback sheets will also be customised in this manner; displaying:
- A ‘from’ source. Sheet will be printed for each possible piece of feedback in that room: ie adjudicators will each get a sheet for their panellists and trainees while teams and panellists will get sheets for the chair.
- The specific questions you established when configuring the adjudicator feedback questions
- The room number
To print the ballots for each round, you would go to the Display page for that round, the click one of the two relevant print links. This opens a new window. In each window, you then use your browser’s print function (CTRL-P). In the resulting print interface (from your browser) you’ll want to turn background graphics on, header/footers off, and set the layout to portrait (feedback sheets) or landscape (score sheets).
Typically you’d save these to PDF for printing, although you should be able to print straight from this dialogue box.
Caution
Printing works best in Safari and Firefox; use those if possible.
Team Standings Rules¶
In Tabbycat, you can choose how teams are ranked in the team standings. For example, at Australs, teams are ranked first on the number of wins, and second on their total speaker score. The setting that specifies how teams are ranked is called the team standings precedence. The team standings precedence is used
- when displaying the team tab,
- whenever a power-paired draw is generated, and
- when computing which teams are in the break.
When you choose the team standings precedence, you choose from a list of metrics. Then, in the standings, teams will be sorted first by the first metric, then by the second metric, and so on. You must choose at least one metric, and you can choose up to eight. Teams tied on all metrics will have the same rank.
Metric | Description |
---|---|
Wins | How many debates the team has won. |
Points | How many points the team has. Currently, this is just a synonym for wins, and differs only in column labelling. |
Points (2/1/0) | How many points the team has, where teams earn 2 points for a win, 1 point for a loss and 0 points for a forfeit. |
Total speaker score | The sum of all speaker scores attained in all debates. |
Average speaker score | The average total speaker score over all debates the team has had, not counting debates where they or their opponents forfeited. |
Sum of margins | The sum of all margins. Wins are positive, losses are negative. |
Average margin | The average margin over all debates the team has had, not counting debates where they or their opponents forfeited. |
Draw strength | The sum of the number of wins of every team this team has faced so far. This is also known in some circuits as win points, opp wins or opp strength. |
Votes/ballots carried | The number of adjudicators that gave this team a win across all of their debates. Also known as the number of ballots or judges a team has. In cases where the panel is smaller or larger than 3, this number is normalised to be out of 3. For example, if a panel of five splits 3–2, then the winning team is recorded as gaining 1.8 votes, and the losing team is recorded as gaining 1.2. This also means that solo adjudicators are always worth three votes. |
Who-beat-whom | If there are exactly two teams tied on all metrics earlier in the precedence than this one, then check if the teams have faced each other. If they have, the team that won their encounter is ranked higher. If they have seen each other more than once, the team that has won more of their encounters is ranked higher. If there are more than two teams tied, this metric is not applied. This metric can be specified multiple times. Each time who-beat-whom occurs, it applies to all the metrics earlier in the precedence than the occurrence in question. |
Who-beat-whom (in divisions) | As for who-beat-whom, but only compares for teams in the same division. That is, the metric applies whenever there are exactly two teams from the same division exactly tied. |
Note
Some debugging information is printed to the logs when some of these metrics are invoked.
Tournament Data Importers¶
This page describes how to write your own tournament data importer. It is aimed at an audience that is familiar with programming in Python, and may be willing to get their head around the Django model if necessary.
The tournament data importer is the class that imports data from one or more files (usually CSV files) into the database. A base class BaseTournamentDataImporter
is in importer/base.py. An example of a data importer is in importer/anorak.py.
Todo
This page is incomplete. If you’re finding this information insufficient, please contact Chuan-Zheng using the contact details in the Authors section.
Why write your own?¶
While Tabbycat has standard import formats, you might find that none of them fit the data that you need to import.
It’s not possible to devise a single, universally-convenient import file format. Tabbycat supports way too many permutations of configurations for this to be workable. Instead, we provide the ones that have been useful before and are therefore likely to be useful again—but if your tournament has different needs, you might decide that it’s easier to write an importer to conform to you, rather than conform to the importer.
A base importer class abstracts away most of the nitty-gritty of parsing files, allowing new importers to focus on their interpretation with as little code as possible.
To allow new importers to be written with as little code as possible, most of the work is abstracted to the base class. The flipside of this abstraction is that it induces a learning curve.
Basic workflow¶
- Choose a name. We name importers after items of clothing in alphabetical order (starting at ‘Anorak’).
- Write a subclass of
BaseTournamentDataImporter
. - Write the front-end interface. This will probably be a Django management command.
A basic example¶
It’s easiest to start with an example. Here’s a basic importer with just one import method, which imports adjudicators.
from .base import BaseTournamentDataImporter, make_lookup, make_interpreter
from participants.models import Person, Adjudicator
class ExampleTournamentDataImporter(BaseTournamentDataImporter):
lookup_gender = make_lookup("gender", {
("male", "m"): Person.GENDER_MALE,
("female", "f"): Person.GENDER_FEMALE,
("other", "o"): Person.GENDER_OTHER,
})
def import_adjudicators(self, f):
"""Imports adjudicators. `f` is a file object."""
interpreter = make_interpreter(
institution=Institution.objects.lookup,
gender=self.lookup_gender,
tournament=self.tournament
)
counts, errors = self._import(f, Adjudicator, interpreter)
return counts, errors
Let’s break this down. The method import_adjudicators()
takes a single
argument, a file object representing the CSV file. Most of the work is
passed off to self._import()
. This helper method is defined in
BaseTournamentDataImporter
and is where most of the intelligence lies.
When called, self._import(f, model, interpreter)
does the following:
- It reads the CSV file using a csv.DictReader. A
DictReader
iterates through the CSV file, yielding a dict for each line, whose keys are given by the column header names in the first row of the file. - On each line:
- It passes the dict given by the
DictReader
tointerpreter
. The interpreter modifies the dict (or creates a new one) to prepare it for the model constructor, and returns it.- The dict returned by
interpreter
is then passed as keyword arguments to themodel
constructor.
So in very simplified form, self._import(f, model, interpreter)
does this:
def _import(self, f, model, interpreter): reader = csv.DictReader(f) for line in reader: kwargs = interpreter(line) inst = model(**kwargs) inst.save()
(There’s a lot more to it than that, but that’s the basic idea.)
Important
A consequence of relying on column headers to identify fields is
that the header names in CSV files must match model field names exactly,
unless they are deleted by the interpreter using the DELETE
keyword (see
below).
Interpreters¶
The main task of an importer, then, is to provide interpreters so that self._import
knows how to interpret the data in a CSV file. An interpreter takes a dict and
returns a dict. For example:
def interpreter(line):
line['institution'] = Institution.objects.lookup(line['institution'])
line['gender'] = self.lookup_gender(line['gender'])
line['tournament'] = self.tournament
return line
This interpreter does the following:
- Replaces
line['institution']
with an Institution object, by looking up the original value by name. - Replaces
line['gender']
with aPerson.GENDER_*
constant. We’ll come back to how this works later. - Adds a new
line['tournament']
entry to the dict, being the Tournament object represented byself.tournament
, the tournament that was passed to the importer’s constructor. - Leaves all other entries in the dict unchanged.
This looks simple enough, but it’s very robust. What if a cell in the CSV file is blank, or what if the file omits a column? (For example, some tournaments might not collect information about participant gender, so Tabbycat doesn’t require it.) We could deal with these scenarios on a case-by-case basis, but that’s cumbersome.
Instead, we provide a make_interpreter
method that returns an interpreter
method which, in turn, takes care of all these details. This way, all you have
to do is provide the functions that transform fields. So the following is
equivalent to the above, but better:
interpreter = make_interpreter(
institution=Institution.objects.lookup,
gender=self.lookup_gender,
tournament=self.tournament
)
Notice that we provided a callable in two of these keyword arguments, and a
(non-callable) Tournament object to the third. make_interpreter
is smart
enough to tell the difference, and treat them differently. What it does with
each field depends on (a) whether a value exists in the CSV file and (b) what
transformation function was provided, as summarised in the following table:
Value in CSV file | Transformation | Action |
---|---|---|
provided and not callable | populate model field with interpreter value | |
does not exist or blank | callable or not provided | do not pass to model constructor |
exists and not blank | callable | call interpreter on column value, pass result to model constructor |
exists and not blank | not provided | pass column value directly to model constructor |
Tip
- If a transformation isn’t an existing method, you might find
lambda functions
useful. For example:
lambda x: Speaker.objects.get(name=x)
. - You shouldn’t check for mandatory fields. If a mandatory field is omitted,
the model constructor will throw an error, and
self._import()
will catch the error and pass a useful message on to the caller. On the other hand, if it’s an optional field in the model, it should optional in the importer, too. Similarly, interpreters generally shouldn’t specify defaults; these should be left to model definitions. - You don’t need to include interpreter transformations for things like
converting strings to integers, floats or booleans. Django converts strings
to appropriate values when it instantiates models. So, for example, adding
test_score=float
to the above interpreter would be redundant.
More complicated interpreters¶
If you have a column in the CSV file that shouldn’t be passed to the model
constructor, you can tell the interpreter to remove it by using the special
DELETE
argument:
interpreter = make_interpreter(
institution=Institution.objects.lookup,
DELETE=['unwanted_column_1', 'unwanted_column_2']
)
The make_interpreter
can only deal with modifications where each field is
modified separately of the others (or not at all). If you want to combine
information from multiple fields, you need to write your interpreter the long
way (perhaps calling a function returned by make_interpreter
to do some of
the work).
On the other hand, if you don’t need to do any transformations involving some
sort of object or constant lookup, then you can just omit the interpreter
argument of self._lookup()
, and it’ll just leave the fields as-is.
Lookup functions¶
In the above example, we used a function self.lookup_gender
to convert from
the text in the CSV file to a Person.GENDER_*
constant. To make this easier,
the importer provides a convenience function to define such lookup functions.
Let’s look at the relevant lines again:
lookup_gender = make_lookup("gender", {
("male", "m"): Person.GENDER_MALE,
("female", "f"): Person.GENDER_FEMALE,
("other", "o"): Person.GENDER_OTHER,
})
This should be a member of your subclass, in our case,
ExampleTournamentDataImporter
. It generates a function that looks something
like:
@staticmethod
def lookup_gender(val):
if val in ("male", "m"):
return Person.GENDER_MALE
elif val in ("female", "m"):
return Person.GENDER_FEMALE
elif val in ("other", "o"):
return Person.GENDER_OTHER
else:
raise ValueError("Unrecognised value for gender: %s" % val)
The make_lookup
function takes two arguments. The first is a text
description of what it’s looking up; this is used for the error message if the
value in the CSV file isn’t recognised. The second is a dict mapping tuples
of valid strings to constants.
Debugging output¶
The BaseTournamentDataImporter
constructor accepts a loglevel
argument:
importer = MyTournamentDataImporter(tournament, loglevel=logging.DEBUG)
If loglevel
is set to logging.DEBUG
, the importer will print information
about every instance it creates.
You can also pass in a logger for it to use (instead of the default one) with
the logger
argument.
User Accounts¶
For obvious reasons, user logins are required to data entry and administrative functions. There are (conceptually) four levels of access:
Access | Should be used by | Grants access to | Is capable of |
---|---|---|---|
Public | The public | Publicly available information. | Viewing things, and submitting new ballots/feedback if that function is enabled. |
Assistant | Data entry helpers | Specialised data entry (ballots and feedback). | Entering and confirming ballots and feedback. |
Superuser | Adjudication core | The Tabbycat admin interface. | Generating draws, editing ballots, feedback and adjudicator scores, checking in ballots and people. |
Staff | Tab director | The Tabbycat admin and edit database interfaces. | Editing the database directly. |
Account roles¶
If the adjudication core and tab directors will be helping with data entry, you should create a “assistant” account for them as well. These people will then have two accounts each: one with assistant access, which is used for data entry, and one with superuser access, which is used for everything else.
Specifically, the Tabbycat admin interface should not, in general, actually be used for data entry. That interface doesn’t include some checks that are important for data integrity assurance. It should be used only to override the normal data entry procedure, for example, to unconfirm a ballot or edit a score.
The Edit Database interface should certainly not be used except where it is actually necessary. There are a few functions which require this, but as a principle, it shouldn’t be used as a matter of course.
Adding accounts¶
To add an account:
- Go to BASE_URL/admin/auth/user/ and click “Add user” in the top right.
- Ask the user to enter a username and password.
- Only they should know what the password is.
- If you’re hosting on the internet, all passwords should be at least moderately strong!
- Passwords are stored as hashes, not as raw passwords, so it’s (in theory, practically) impossible for you to figure out what their password is.
- What you do next depends on what sort of account you’re creating:
- If this is an assistant account, click “Save” or “Save and add another”. (Any account not marked staff or superuser is an assistant account.)
- If they’re being assigned superuser and/or staff privileges, then click “Save and continue editing”, and check the appropriate boxes before clicking “Save”.
- If you also wanted their names to be associated with their accounts, click “Save and continue editing” and fill out the relevant fields. But their names etc. aren’t used for anything by Tabbycat.
Venue Constraints¶
Attention
This changed in version 1.3. Previously, venue constraints used venue constraint categories. Now they use venue categories and venue groups no longer exist.
Tabbycat supports a basic form of venue constraints. A venue constraint is a requirement that a particular team, adjudicator, institution or division be assigned to a venue in a particular venue category. Typical uses would include:
- Meeting venue accessibility requirements of particular teams (e.g. step-free access)
- Placing adjudication core and tab team members close to the tab room
- Keeping all debates in a division in one location
Constraints apply to venue categories, not individual venues. That is, you specify that (say) a team should be given a venue from a particular list of venues. Of course, it’s permissible for a venue category to have only one venue in it.
The algorithm used to satisfy venue constraints is not guaranteed to be optimal. In some rare cases, it may propose an allocation that fails some constraints, even though some other allocation would have satisfied all (or more) constraints. In almost all practical circumstances, however, it should work, and save human effort (and time) in specially allocating rooms.
Adding venue categories¶
Before you add venue constraints, you first need to add venue categories. Each venue category is a list of venues, typically satisfying a particular need. For example, you might have a category for each of the following:
- Venues with step-free access
- Venues that are close to general assembly (the briefing room)
- Venues that are close to the tab room
- Venues that are, or venues that are not, being live-streamed
Each venue can be in as many categories as you like (or none at all).
To add a venue category, go to the Edit Database area (under Setup), scroll down to “Venues” and click “Venue categories”. Then click the + Add venue category button in the top-right of the page. You’ll see a page with this on it:
Give your category a name (like “Step-free access”), assign it some venues, then click one of the “Save” buttons.
Adding venue constraints¶
To add a venue constraint, go to the Edit Database area (under Setup), scroll down to “Venues”, and click “Venue Constraints”. Then click the + Add venue constraint button in the top-right of the page. You’ll see a page with this on it:
For each constraint, you need to specify four things:
Category | The venue category to which the subject of this constraint should be locked. |
Priority | This is a number used to resolve conflicts between constraints. Constraints with higher priority (greater number) take precedence over those with lower priority. If none of your constraints will ever conflict, then the priority is arbitrary (but it must still be specified). |
Subject content type | The type of subject to which this constraint relates: adjudicator, team, institution or division. |
Subject ID | Which adjudicator, team, institution or division the constraint relates to. The textbox takes a number (the ID of the object in the database), but you can search for the subject by clicking on the search icon next to it. This will bring up a table of objects of the type specified in “subject content type” for you to choose from. (You need to select the subject content type first.) |
Applying venue constraints¶
If you don’t have any venue constraints for adjudicators, venue constraints are applied automatically when the draw is generated.
However, if you have one or more venue constraints for adjudicators, it’s not possible to take adjudicator venue constraints into account during draw generation, because the adjudicator allocation isn’t known then. You’ll need to run the venue allocation yourself after you’ve allocated adjudicators.
To run venue allocation, go to Edit Venues (while looking at the draw), then in the screen where you can edit venues, click the Auto Allocate button. You can also do this at any other point (say, after adding a new venue constraint) if, for whatever reason, you would like to re-run the venue allocation algorithm.
If a venue constraint couldn’t be met, a message will show in the “conflicts/flags” column of the draw. A constraint might not be met for a number of reasons:
- It could be that constraints of different parties (say, one team and one adjudicator) conflicted, so only one could be fulfilled.
- It could be that all available rooms in the relevant category were already taken by other, higher-priority constraints.
- It could just be one of those edge cases that’s too hard for the naïve algorithm to handle.
Currently, Tabbycat doesn’t tell you which of these happened, so if the venue allocation fails to meet all your constraints, it’s on you to figure out why. In most scenarios, we imagine you’ll have few enough constraints that this will be obvious; for example, if the chief adjudicator is judging a team with accessibility requirements, it might be obvious that the latter’s constraint took priority. We might in future add support for more useful guidance on conflicting constraints, but we currently consider this to be of low priority.
Support¶
There are a number of ways to report bugs, ask for help, or submit feedback.
Facebook¶
Our Facebook group is a good place to ask for help. It’s also a good place to keep up with new releases and participate in more general discussions of features and ideas.
GitHub¶
Adding an issue to our GitHub repository is a great way to let us know about bugs or writeup suggestions for how to improve Tabbycat. Pull requests are also encouraged!
When submitting bugs or reporting errors please let us know your site address (if installed online) or operating system (if local) along with a complete description of the problem along with any error messages.
Email¶
Feel free to contact the maintainers directly if you are not able to access Facebook or GitHub.
Authors¶
Tabbycat was authored by Qi-Shan Lim for Auckland Australs 2010. The current active developers are:
Please don’t hesitate to contact us with any suggestions, expressions of interest or generally anything relating to Tabbycat.
Change Log¶
1.3.1¶
Release date: 26 May 2017
- Fixed bug that allowed duplicate emoji to be occasionally generated
1.3.0 (Genetta)¶
Release date: 9 May 2017
- Added the ability to mark speeches as duplicates when entering ballots so that they will not show in speaker tabs, intended for use with ‘iron-man’ speeches and swing speakers
- Reworked venue constraints and venue display options by streamlining “venue groups” and “venue constraint categories” into a single “venue category” type, with options for how they are used and displayed
- Relocated the Random (now renamed ‘Private’) URL pages to the Setup section and added pages for printing/emailing out the ballot submission URLs
- Reworked the simple data importer (formerly the visual importer) to improve its robustness
- Improved guards against having no current round set, and added a new page for manually overriding the current round (under Configuration).
- Added a preference for controlling whether assistant users have access to pages that can reveal draw or motions information ahead of their public release
- Added the ability to limit tab releases to a given number of ranks (i.e. only show the top 10 speakers)
- Added the ability to redact individual person’s identifying details from speaker tabs
- Added the ability for user passwords to be easily reset
- Added a minimal set of default feedback questions to newly created Tournaments.
- When a tournament’s current round is set, redirect to a page where it can be set, rather than crashing
- A number of other minor bug fixes and enhancements
1.2.3¶
Release date: 17 March 2017
- Improved the display of the admin ballot entry form on mobile devices
- A number of other minor bug fixes
1.2.2¶
Release date: 4 March 2017
- Protected debate-team objects from cascaded deletion, and added warning messages with guidance when users would otherwise do this
- A number of other minor bug fixes
1.2.1¶
Release date: 25 February 2017
- Printable feedback forms will now display the default rating scale, any configured introduction text, and better prompt you to add additional questions
- A number of other minor bug fixes
1.2.0 (Foldex)¶
Release date: 15 February 2017
- Changed the core workflow by splitting display- and motion- related activities into separate pages to simplify each stage of running a round
- Added support for Docker-based installations to make local/offline installations much more simple
- Added a “Tabbykitten” version of Tabbycat that can be deployed to Heroku without a needing a credit/debit card
- Added button to load a demo tournament on the ‘New Tournament’ page so it is easier to test-run Tabbycat
- Changed venue groups to be separate to venue constraint categories
- Modified the licence to clarify that donations are required for some tournaments and added a more explicit donations link and explanation page
- Added information about autosave status to the adjudicator allocations page
- Added configurable side names so that tournaments can use labels like “Proposition”/”Opposition” instead of “Affirmative”/”Negative”
- Started work on basic infrastructure for translations
1.1.7¶
Release date: 31 January 2017
- Yet more minor bug fixes
- The auto-allocation UI will now detail your minimum rating setting better
- Added guidance on database backups to documentation
1.1.6¶
Release date: 19 January 2017
- A number of minor bug fixes
- Added basic infrastructure for creating tabbycat translations
1.1.4¶
Release date: 25 November 2016
- Redesigned the footer area to better describe Tabbycat and to promote donations and related projects
- Slight tweaks to the site homepage and main menus to better accomodate the login/log out links
- A few minor bug fixes and improvements to error reporting
1.1.3¶
Release date: 15 September 2016
- Fixed bug affecting some migrations from earlier versions
- Made latest results show question mark rather than crash if a team is missing
- Fixed bug affecting the ability to save motions
- Fixed bug preventing draw flags from being displayed
1.1.2¶
Release date: 14 September 2016
- Allow panels with even number of adjudicators (with warnings), by giving chair the casting vote
- Removed defunct person check-in, which hasn’t been used since 2010
- Collapsed availability database models into a single model with Django content types
- Collapsed optional fields in action log entries into a single generic field using Django content types
- Added better warnings when attempting to create an elimination round draw with fewer than two teams
- Added warnings in Edit Database view when editing debate teams
- Renamed “AIDA pre-2015” break rule to “AIDA 1996”
1.1.1¶
Release date: 8 September 2016
- Fixed a bug where the team standings and team tab would crash when some emoji were not set
1.1.0 (Egyptian Mau)¶
Release date: 3 September 2016
- Added support for the United Asian Debating Championships style
- Added support for the World Schools Debating Championships style
- Made Windows 8+ Emoji more colourful
- Fixed an incompatability between Vue and IE 10-11 which caused tables to not render
- Minor bug fixes and dependency updates
1.0.1¶
Release date: 19 August 2016
- Fixed a minor bug with the visual importer affecting similarly named institutions
- Fixed error message when user tries to auto-allocate adjudicators on unconfirmed or released draw
- Minor docs edits
1.0.0 (Devon Rex)¶
Release date: 16 August 2016
- Redesigned and redeveloped adjudicator allocation page
- Redesigned interface, featuring clearer displays of conflict and diversity information
- Changes to importances and panels are now automatically saved
- Added debate “liveness” to help identify critical rooms—many thanks to Thevesh Theva
- Panel score calculations performed live to show strength of voting majorities
- New features
- Added record pages for teams and adjudicators
- Added a diversity tab to display demographic information about participants and scoring
- Significant general improvements
- Shifted most table rendering to Vue.js to improve performance and design
- Drastically reduced number of SQL queries in large tables, e.g. draw, results, tab
- Break round management
- Completed support for break round draws
- Simplified procedure for adding remarks to teams and updating break
- Reworked break generation code to be class-based, to improve future extensibility
- Added support for break qualification rules: AIDA Australs, AIDA Easters, WADL
- Feedback
- Changed Boolean fields in AdjudicatorFeedbackQuestion to reflect what they actually do
- Changed “panellist feedback enabled” option to “feedback paths”, a choice of three options
- Dropped “/t/” from tournament URLs and moved “/admin/” to “/database/”, with 301 redirects
- Added basic code linting to the continuous integration tests
- Many other small bug fixes, refactors, optimisations, and documentation updates
0.9.0 (Chartreux)¶
Release date: 13 June 2016
- Added a beta implementation of the break rounds workflow
- Added venue constraints, to allow participants or divisions to preferentially be given venues from predefined groups
- Added a button to regenerate draws
- Refactored speaker standings implementation to match team standings implementation
- New standings metrics, draw methods, and interface settings for running small tournaments and division-based tournaments
- Improved support for multiple tournaments
- Improved user-facing error messages in some scenarios
- Most frontend dependencies now handled by Bower
- Static file compilation now handled by Gulp
- Various bug fixes, optimisations, and documentation edits
0.8.3¶
Release date: 4 April 2016
- Restored and reworking printing functionality for scoresheets/feedback
- Restored Edit Venues and Edit Matchups on the draw pages
- Reworked tournament data importers to use csv.DictReader, so that column order in files doesn’t matter
- Improved dashboard and feedback graphs
- Add separate pro speakers tab
- Various bug fixes, optimisations, and documentation edits
0.8.2¶
Release date: 20 March 2016
- Fixed issue where scores from individual ballots would be deleted when any other panel in the round was edited
- Fixed issue where page crashes for URLs with “tab” in it but that aren’t recognized tab pages
0.8.1¶
Release date: 15 March 2016
- Fixed a bug where editing a Team in the admin section could cause an error
- Added instructions on how to account for speakers speaking twice to docs
- Venues Importer wont show VenueGroup import info unless that option is enabled
0.8.0 (Bengal)¶
Release date: 29 February 2016
- Upgraded to Python 3.4, dropped support for Python 2
- Restructured directories and, as a consequence, changed database schema
- Added Django migrations to the release (they were previously generated by the user)
- Migrated documentation to Read The Docs
- New user interface design and workflow
- Overhauled tournament preferences to use django-dynamic-preferences
- Added new visual data importer
- Improved flexibility of team standings rules
- Moved data utility scripts to Django management commands
- Changed emoji to Unicode characters
- Various other fixes and refinements
0.7.0 (Abyssinian)¶
Release date: 31 July 2015
- Support for multiple tournaments
- Improved and extensible tournament data importer
- Display gender, region, and break category in adjudicator allocation
- New views for online adjudicator feedback
- Customisable adjudicator feedback forms
- Randomised URLs for public submission
- Customisable break categories
- Computerised break generation (break round draws not supported)
- Lots of fixes, interface touch-ups and performance enhancements
- Now requires Django 1.8 (and other package upgrades)
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
Licence Information¶
We haven’t released Tabbycat under an open-source licence, so there is no formal and general right to use this software. Nonetheless, you’re welcome to freely use Tabbycat to help run a debating tournament if it is a not-for-profit and not-for-fundraising activity. A voluntary donation of A$1 (Australian dollar) per team would be greatly appreciated, and would help us meet costs and justify our ongoing work and support for Tabbycat users. (A donation link is in the footer of your Tabbycat site.)
Use at for-profit or fundraising tournaments¶
If you use Tabbycat at a tournament where any individual or organisation is making a profit or raising funds (other than to cover the direct costs of the tournament), you or your tournament must make a donation of A$1 (Australian dollar) per team to the Tabbycat maintenance team, as outlined in each tournament’s donation page (the link is in the footer of your Tabbycat site). This includes instances where organisations run tournaments partly as fundraising activities and applies even if the organisation itself is a non-profit.
While we suggest that non-profit, non-fundraising tournaments budget for a donation of A$1 per team, it is not required in order for such tournaments to use Tabbycat.
Modifications to and redistributions of Tabbycat¶
We grant you permission to modify and/or redistribute Tabbycat, provided that
- you do not receive any payment for this modification and/or redistribution,
- if you modify Tabbycat, you add prominent notices stating that you modified it,
- all references and functionality relating to donations are kept intact, and
- this licence page and all attributions of authorship are included as-is.
Modifying Tabbycat for payment, or using a version of Tabbycat that has been modified for payment, is strictly prohibited without our express permission.
If you use a version of Tabbycat that has been modified by you or a third party to run a for-profit or fundraising tournament, the abovementioned donation of A$1 per team is still required.
Disclaimer of warranty and liability¶
We work on this software in our spare time and make it available for not-for-profit use in the hope that it will benefit the debating community. It is provided “as is”, without any warranty of any kind, express or implied, including without limitation any warranties of merchantability and fitness for a particular purpose, and we disclaim all legal liability. By using Tabbycat, you agree that none of its contributors will be held liable for any loss or claim arising directly or indirectly from using the software, or for any loss or claim otherwise in connection with the software.
Tournament History¶
A list of tournaments (that we know of) which have used Tabbycat.
2016¶
- ACT Debating Union Grades
- Australian Easters
- Canton IV
- IIT KGP PD
- Joynt Scroll
- Malaysia Debate Open 2016
- Mad Mini
- New Zealand Easters
- Perth Australs
- Pre SSIDC
- Thailand United Asian Debating Championships
- The National Law School Debate
- The Khazak National Schools Debating Championship
- The Western Australian Debating League
- The Western Sydney Open
- USU Grand Slam
2015¶
- ACT Debating Union Grades
- Another Day at Melbourne
- ANU Pre-Australs
- ALSA E-Comp
- Auckland Schools Regionals
- Bali United Asian Debating Championships
- Daejeon Australs
- Derozio Memorial Debate
- Joynt Scroll
- Malaysia Debate Open
- Mad Mini
- President’s Cup
- RMIT Women’s Open
- New Zealand Easters
- The Western Australian Debating League
- The National Law School Debate
- UNSW/UTS Easters
2014¶
- Another Day at Melbourne
- Joynt Scroll
- NTU United Asian Debating Championships
- Otago Australs
2012¶
- Wellington Australs
2010¶
- Auckland Australs