Tabbycat User Guide

Tabbycat is a draw tabulation system for parliamentary debate tournaments. It supports two-team formats such as Australs, World Schools, Asians, Australian Easters and all New Zealand formats, as well as British Parliamentary (WUDC). It is also highly configurable, supporting many custom variations of the above formats too. If you’re looking for a general overview of the software, check out our README on Github.

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 macOS.

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 macOS 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/TabbycatDebate/tabbycat.git
git checkout v2.0.7                               # 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 macOS 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/TabbycatDebate/tabbycat.git
git checkout v2.0.7                               # 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

1. Navigate to your Tabbycat directory:

   cd path/to/my/tabbycat/directory
   

2. 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 prevent deploy_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.

1. Place your CSV files in data/yourtournamentname, as described in Importing Initial Data.

2. 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 of heroku in the last command above.

Advanced users

You might like to create a new branch to keep this data off your master branch.

3. 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, 8 preliminary rounds and heavily used adjudicator feedback, ended up at around 30,000 rows.
• The Asia BP championships 2017 had 100 teams, 6 preliminary rounds, and mandatory feedback (i.e. 100% return rates) used 15,000 rows.
• A 3 vs 3 tournament with 54 teams, 5 preliminary rounds, and which only lightly used adjudicator feedback ended up using around 4,500 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:

• Custom Domain Names for Apps
• Heroku SSL

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:

• Installing Locally on Linux
• Installing Locally on macOS
• Installing Locally on Linux on Windows (WSL)
• Installing Locally on Windows

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

If you need an offline copy of Tabbycat, installing using Docker should be simpler and quicker than using the “Install Locally on…” instructions for your operating system. However if a Docker installation doesn’t work as outlined below, it’s harder to address what isn’t working. If you encounter any problems with Docker, we recommend using the “Install Locally on…” option as a fallback, but if you need to do so, please also report the issue you’re having on GitHub or 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

1. Go to the page for our latest release.
2. Download the zip or tar.gz file.
3. Extract all files in it to a folder of your choice.

2. Install Docker

If using macOS or Linux

• Install the Docker Community Edition (stable) from the Docker store page.

If using Windows 10 Pro, Enterprise, or Education Edition

1. Install the **Docker Community Edition (stable)* from the Docker store page.
2. 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.
3. Once Docker has finished installing, open up the newly-installed Docker application, then right-click the app’s icon (the whale) in the Taskbar.
4. 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 macOS, Linux or Windows Pro/Enterprise/Education.

1. 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.

2. Browse to the location where you extracted Tabbycat to. Open up the bin folder there. Within that folder:

   • If you’re on macOS, 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 run docker-compose up.

3. 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.

4. 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.

1. Start the Docker Quickstart Terminal.

2. Run the command docker-machine ip. Take note of the IP address it shows, for example:

   $ docker-machine ip
   192.168.99.100
   

3. Navigate to the Tabbycat folder (i.e. the folder containing README.md) and run docker-compose up.

4. 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.

5. 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 installation 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, consider installing using Docker, which is a shorter process than the one 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 Tabbycat uses (Python, PostgreSQL, etc.) will make things easier, 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_6.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/TabbycatDebate/tabbycat/archive/v2.0.7.tar.gz
tar xf v2.0.7.tar.gz
cd tabbycat-2.0.7
# or
git clone https://github.com/TabbycatDebate/tabbycat.git
git checkout v2.0.7                                         # 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
npm run gulp build
dj collectstatic
dj createsuperuser
dj runserver

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_6.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/TabbycatDebate/tabbycat/archive/v2.0.7.tar.gz
$ tar xf v2.0.7.tar.gz
$ cd tabbycat-2.0.7

If you’ve used Git before, you might prefer to clone our GitHub repository instead:

$ git clone https://github.com/TabbycatDebate/tabbycat.git
$ git checkout v2.0.7                              # 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.

1. Create a new user account with a password, replacing myusername with whatever name you prefer. If you don’t know what username to pick, use tabbycat.

$ sudo -u postgres createuser myusername --pwprompt

Tip

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 a local all myusername md5 line to the pg_hba.conf file, or you could define a mapping in pg_ident.conf and append the map= option to the local 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.

2. 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!

1. Navigate to your Tabbycat directory:

   $ cd path/to/my/tabbycat/directory
   

2. Start a new virtual environment. We suggest the name venv, though it can be any name you like:

$ python3 -m venv venv

3. Run the activate script. This puts you “into” the virtual environment:

   $ source venv/bin/activate
   

4. Install Tabbycat’s requirements into your virtual environment:

   $ pip install --upgrade pip
   $ pip install -r requirements_common.txt
   $ npm install
   

5. 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',
    }
}

6. Navigate to the tabbycat sub-directory, initialize the database, compile the assets, and create a user account for yourself:

   $ cd tabbycat
   $ dj migrate
   $ npm run gulp build
   $ dj collectstatic
   $ dj createsuperuser
   

7. Start Tabbycat!

$ dj runserver

It should show something like this:

serving on http://127.0.0.1:8000

8. Open your browser and go to the URL printed above. (In the above example, it’s http://127.0.0.1:8000.) 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
$ dj runserver

Installing Locally on macOS

Is this the best installation 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 macOS, consider installing using Docker, which is a shorter process than the one 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 Tabbycat uses (Python, PostgreSQL, etc.) will make things easier, 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. macOS 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 6 macOS Installer (.pkg)

2. Get the source code

1. Go to the page for our latest release.
2. Download the zip or tar.gz file.
3. 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 v2.0.7 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.

1. Create a new user account with a password, replacing myusername with whatever name you prefer. If you don’t know what username to pick, use tabbycat.

$ createuser myusername --pwprompt

Tip

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 a local all myusername md5 line to the pg_hba.conf file, or you could define a mapping in pg_ident.conf and append the map= option to the local 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.

2. Create a new database, replacing mydatabasename with whatever name you prefer, probably the name of the tournament you’re running:

   $ createdb mydatabasename --owner myusername
   

3. In terminal type in:

   $ PATH="/Applications/Postgres.app/Contents/Versions/9.6/bin:$PATH"
   

4. Install Tabbycat

Almost there!

1. Navigate to your Tabbycat directory:

   $ cd path/to/my/tabbycat/directory
   

2. 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',
    }
}

3. Start a new virtual environment. We suggest the name venv, though it can be any name you like:

   $ python3 -m venv venv
   

4. Run the activate script. This puts you “into” the virtual environment:

   $ source venv/bin/activate
   

5. Install Tabbycat’s requirements into your virtual environment:

   $ pip install --upgrade pip
   $ pip install -r requirements_common.txt
   $ npm install
   

6. Navigate to the tabbycat sub folder, initialize the database, compile the assets, and create a user account for yourself:

   $ cd tabbycat
   $ dj migrate
   $ npm run gulp build
   $ dj collectstatic
   $ dj createsuperuser
   

7. Start Tabbycat!

$ dj runserver

It should show something like this:

serving on http://127.0.0.1:8000

8. Open your browser and go to the URL printed above. (In the above example, it’s http://127.0.0.1:8000.) 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
$ dj runserver

Installing Locally on Linux on Windows (WSL)

Is this the best installation 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, consider installing using Docker, which is a shorter process than the one below.

Note

Windows Subsystem for Linux (WSL) was taken out of beta in the Windows 10 Fall Creators Update, which was released in October 2017. On Windows 10 computers, we now recommend this local installation method over installing it directly on Windows.

Requisite technical background

It will help a lot if you have some experience with Linux, but mainly you need to be familiar with command-line interfaces, and you should be willing to install and work with the Windows Subsystem for Linux. You might need to be prepared to familiarise yourself with aspects of WSL not covered in these instructions. While a background in the specific tools Tabbycat uses (Python, PostgreSQL, etc.) will make things easier, it’s not necessary: we’ll talk you through the rest.

You might need to check that you have the Fall Creators Update (build 1709) first.

Windows Subsystem for Linux is only available on Windows 10. If you have an older version of Windows, install Tabbycat locally on Windows instead.

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, when these instructions were first written, the PostgreSQL server didn’t work on the Windows Subsystem for Linux. A fix for this is reportedly in the Fall Creators Update, but we haven’t tried it yet. (Of course, you’re welcome to, and we’d love to hear from you if you succeed.)

This has a number of consequences:

1. You’ll still install the PostgreSQL client on the Linux subsystem, using that to communicate with the server on Windows.
2. Because you won’t install the PostgreSQL server, you need to install libpq-dev instead, in order for the psycopg2 module to work.
3. 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 shell:

curl -sL https://deb.nodesource.com/setup_6.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/TabbycatDebate/tabbycat/archive/v2.0.7.tar.gz
tar xf v2.0.7.tar.gz
cd tabbycat-2.0.7
# or
git clone https://github.com/TabbycatDebate/tabbycat.git
git checkout v2.0.7                                         # 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
dj migrate
npm run gulp build
dj collectstatic
dj createsuperuser
dj runserver

1. Install dependencies

If you don’t already have it, install the Windows Subsystem for Linux.

Then, follow these instructions:

• 1(a). Python in the Linux instructions, on the Linux subsystem
• 1(b). PostgreSQL in the Windows instructions (in Windows)
• 1(c). Node.js/NPM in the Linux instructions, on the Linux subsystem

2. Get the source code

Follow section “2. Get the source code” in the Linux instructions, on the Linux subsystem.

Attention

You should put the source code somewhere in your Windows file system, not your Linux file system. See this page on the Microsoft Developers blog for why.

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 Linux 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
$ dj runserver

Installing Locally on Windows

Is this the best installation 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, consider installing using Docker, which is a shorter process than the one below.

If you have Windows 10 and any experience with Linux, consider installing it on Linux on Windows (WSL) instead, 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 Tabbycat uses (Python, PostgreSQL, etc.) will make things easier, 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 the latest version of 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 6 Installer (.msi) for either x64 versions of Windows or x86 versions.

2. Get the source code

1. Go to the page for our latest release.
2. Download the zip file.
3. 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 v2.0.7 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.

1. 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.
2. Right-click Login Roles, and click “New Login Role…”

3. 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.)

4. Right-click Databases, and click “New Database…”

5. 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!

1. 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
   

2. 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',
    }
}

3. Start a new virtual environment. We suggest the name venv, though it can be any name you like:

   > python -m venv venv
   

4. 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 RemoteSigned

Read the warning message, then type y to confirm. By default, the execution policy on Windows is Restricted, which does not permit scripts like activate to be run. Changing it to RemoteSigned relaxes it to allow local scripts to be run without checking the signature.

5. 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 install

If 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 install

If 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 before pip 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.

6. Initialize the database and create a user account for yourself:

   > cd tabbycat
   > dj migrate
   > npm run gulp build
   > dj collectstatic
   > dj createsuperuser
   

7. Start Tabbycat!

> dj runserver

It should show something like this:

Starting development server on http://127.0.0.1:8000

8. Open your browser and go to the URL printed above. (In the above example, it’s http://127.0.0.1:8000/). 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
> dj runserver

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 (or who lack an institutional affiliation). 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.

1. Copy and rename the data/demo folder
2. 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 and adjudicators.csv files must match the institutions in the second column of the institutions.csv file. And that all CSV files must end with a blank line.
3. 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

4. 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.

Note

Currently the importtournament command cannot add Adjudicators or Teams without an institutional affiliation. However, these can be imported with the Simpler Importer or edited in the Database area.

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:

1. Check-in the teams, adjudicators, and venues present
2. Generate the draw and allocate the adjudicators
3. Show/release the draw
4. Release/enter the motions
5. Have the debates
6. Enter results
7. 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

1. 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 & Acknowledgements section.

2. Once on the confirmed draw page you can click Edit Adjudicators.

3. 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.

1. 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.

2. 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.

1. Enter the motion text. Either before or after their public release motions can be entered in the Motions section for that round.
2. 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.
3. 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

1. Enter debate results and feedback as they come in (and/or allow online entry of results and feedback).
2. 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.
3. 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 the following system tabs:

• Team Tab
• Speakers Tab
• Replies Tab
• Motions Tab

You can configure the team, speakers and replies tab to display only a certain number of speakers, e.g., to show only a “Top 10 Speakers” tab.

If you defined any speaker categories (for example, Novice, ESL or EFL), a tab for each category marked “public” can also be released using the Release speaker category tabs to public. You can similarly limit each of these tabs to display just the top few speakers, in the definition of the speaker categories. The speaker categories not marked public are not released by this option.

You can also 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.

Tournament Logistics

Unlike the rest of our documentation, this section does not deal with particular features or technical concerns with Tabbycat itself. Instead it is an attempt to outline the logistics of tab direction and aims to be of general relevance for people running major tournaments. At present, it is organised by the various ‘stages’ of tabbing a tournament, and most of the content takes the form of check-lists or comments designed to highlight and provide guidance on common issues.

Whilst it aims for general relevance, we should note that this guide is relatively opinionated and mostly written from the perspective of people whose primary experience is tabbing at Australasian tournaments using Tabbycat. That said, we welcome feedback and additions that can account for different format and regional considerations. In the future, if the guide becomes more general and more extensive, it could be spun off into a separate project.

Note

As with the rest of our documentation, this page is open-source and we welcome feedback and contributions. Note also that we’ve formatted this guide a single page to reduce clutter, but the sub-sections in the sidebar can be used to help navigate across sections.

Planning and Preparation

This section aims to outline concerns that occur in the months before the tournament: after you have agreed to help with tabbing and while the organising committee and adjudication core are deciding how they want to run key processes such as registration and feedback. It is organised in terms of who you should coordinate with in order to plan for a well-tabbed tournament.

General Notes

You should avoid being the sole person responsible for that tab unless it is a small tournament. There are many cases where you want to be in several places at once and the easiest way to accommodate that is by having co-directors or trusted assistants. Few tab decisions require a single source of authority; it is far better to have multiple people available to share responsibilities around.

In a similar manner, it is worth considering how you can use the tournament to help train other people. Typically, knowledge of tabbing is concentrated in relatively few people and gained mostly through on-the-ground experience; meaning that every tournament should be approached as rare opportunity to help spread knowledge about tabbing more widely in a circuit. Consider reaching out to institutions or the tournament as a whole to see if they have anyone who would be interested in helping out.

Convenors

It might sound obvious but it will pay to have a very thorough conversation about the tab process (more or less the contents of this document) with the convenors a few months out from the tournament. Do this even if you know the convenors to be knowledgeable or experienced debaters. Key concerns are:

• Whether internet access will be available and whether participants can be presumed to have smart phones. This has an obvious impact on how online feedback, ballots, and draw release is done. Note that Eduroam is not necessarily a reliable guarantee of access; many participants will come from universities who don’t have access to it or will need to follow a setup process that is onerous or requires them to be at their home institution.
• What kind of room is the tab room going to be? Is it possible to optimize its placement when the bookings for rooms are made? Key details include: How large is it? Does it have a sufficient amount of desk space (for data entry)? Does it have a good projector (for allocations)?
• If they have the resources, having an adjacent room available for just the adjudication core to use can also be useful. While you want to work closely with the adjudication core, they may want to discuss sensitive information (motions, equity) in a space without volunteers present; or they might at times get in the way of things, such as by eating lunch in the middle of a frenetic ballot entry process.
• Ensure that plans are made for food to be brought to tab room. Otherwise you will starve and the adjudication core will swan off to lunch. Having regular access to caffeine can also be similarly essential to some adjudication and tab teams.
• What kind of printers will be available? Can the tournament buy/borrow one? This is obviously a key consideration for pre-printed ballots. Also try and ensure there are back-up printing options if possible. Clearly stipulate your need for ink and paper; and try and opt for a black/white laserjet, over an inkjet, if possible.
• What kind of volunteers will be available? How many, and what is their experience level? As a very broad recommendation, you probably want around 1 volunteer for every 10 rooms, assuming volunteers are performing a dual role as data-enterers and ballot-collectors.
• Will the tournament make a donation to whoever maintains the tabbing software you are using? Depending on the license of your tabbing software and the nature of your tournament (for profit vs not for profit) this may be required. Also, if your tab is self-hosted or independently hosted (such as how Tabbycat is generally deployed on Heroku) accounting officers should also be aware that there will be some costs associated with hosting the tab.
• You should also ensure that people helping with the tab are fairly compensated for their flights, registration, etc and that any volunteers are invited along to socials and/or given some other recompense.
• Will Swing teams be available? You should plan to have at least one more than you need. For example, with 39 teams, you should have both an 40th swing team to fill in the draw, and the option to easily assemble an 41st swing team in case a team goes missing. At very large tournaments (say over 150 teams) you should plan for even more swing team capacity — it’s not unheard of for say three teams to vanish all in a single round. In these cases, you should try and ensure that the swing teams are always ready to go — i.e. that that they are pre-formed, you have a clear communication channel with them, and that they distributed/waiting near the debating rooms so they can fill in at a moment’s notice (often you will only find out that teams are missing right as debates are scheduled to start).
• How will critical information be communicated to participants? Consider that in general, Facebook announcements do not reach many people, although paying to boost the posts is often a very cheap way of dramatically raising their effectiveness. In particular also ensure or check how you manage to get in touch with teams or adjudicators who go missing: will they have reliable phone numbers? Can you get a list of institutional reps who can be reliably called? You want to have processes in place for chasing up adjudicators who do things such as make scoring mistakes as soon as possible in order to minimise delays.
• How will critical information be shared between the tab team, adjudication core, and logistics/convening teams? For smaller/medium sized tournaments a group chat augmented by phone calls (assuming everyone knows everyone else’s number) can be sufficient, but even then, you need to ensure that any critical information conveyed privately (i.e. in a call or in person) is conveyed back to the group channel. At very large tournaments (or if you have the resources) walkie-talkies are an excellent way to manage communication — just make sure you have (ahead of time) reserve the different channels to a distinct and known purpose (i.e. general discussion; just the tab team & adjudication core; just convenors).
• As part of this it is ideal if the organising committees can procure local SIM cards for members of the tab team and adjudication core who are not local. These should be relatively generous in their plans — you don’t want to worry about running out of minutes or data if on a critical call or using a hotspot to make critical allocation adjustments.
• At major tournaments you want to arrive at least a day before check-in; and ideally whenever it is that the adjudication core is arriving for their own preparation.

Registration

Having effective registration systems and processes is one of the most important aspects of preparing to tab a large tournament. Bad registration data will make setting up a tab extremely painful and introduces the chance for mistakes or inconsistencies in tab data that will only come to light in the first round. As such:

• You should check in with the registration team and see what they plan to do as soon as possible after being brought on-board. As part of this you should make it clear that you should be consulted on any decisions they make about what data to collect, when to collect it, and how to collect it.
• Registration data should be collected into a shared and live-updating source, such as a Google Sheet. There should be as few canonical sources (ideally one) of data as possible; i.e. there should be a single sheet for individual details, a single sheet for team details, etc; and these should be maintained all the way through to check-in. For both you, and the registration team, having multiple conflicting or outdated copies of data will lead to errors. However, for the registration team these errors can usually be easily sorted out in person (at check-in) but for you that information always needs to be reliable and up to date otherwise what is imported into the tab cannot be trusted.
  • At this point our recommendation is to, in most cases, not use specialised registration systems as they are somewhat less intuitive and less flexible than setting up good Google Forms/Sheets.
  • If, for whatever reason, the registration team are not able to give you ‘live’ access to the data they have on hand, make sure they send you copies of it (even if it is incomplete) well before you need it to setup the tab itself. You want to be able to verify what data is actually being collected and how it is formatted well in advance.
• You should have access to all of the data collected; often registration teams will make (false) assumptions about what you do or do not need. It is better to have everything and then selectively filter out what is not relevant to the tab.
• It is critical that the registration team should check in with you before setting up forms asking for information. Every additional time that registration asks for data there will be less and less participation in the process, so you should aim to gather all that you need at the first opportunity; typically during the canonical individual registration phase. Particular information that should not be overlooked for tab purposes:
  • Individual registration should ask for a person’s team name/number (reconciling these later is painful).
  • Individual registration should ask for any accessibility requirements people may have.
  • Individual registration should ask for the previous institutions of adjudicators.
  • Individual registration should ask for the email addresses of all participants.
  • Individual registration should ask for the phone numbers of adjudicators.
• Independent adjudicators and the adjudication core should follow normal registration procedures. Having them not go through the normal process makes it easy to overlook their data or not get a complete picture of it. For example, adjudication core members might forget to nominate conflicts, or neglect to provide their previous institutions.
• You should confirm how the registration team plans to manage how people check-in to the accommodation in particular. Check-in is when issues with registration data come to light and it is vital that these changes are noted and recorded. Some form of validation of registration data must occur at check-in — in particular all adjudicators should be (individually) verified as present and all members of a team should confirm their presence along with their team’s name/number and speakers.
• After check-in you need to have a definitive list of who is physically present at the tournament so you can run a first-round draw with confidence. Registration must know this and have processes in place for recording people individually as they arrive, and for that data to filter back to you.

Note

If you are using Tabbycat’s secret links for feedback or ballots these are best distributed at check-in. The registration team should know about this, prepare for it, and be provided with the pdfs to print and distribute.

Adjudication cores

If there is a group chat for the adjudication core you probably want to be part of it; even if you don’t contribute much. There are lots of small things that end up being discussed without consideration of how they will affect tab issues and it is also a chance to get to know — ahead of time — the people you will be working with closely over the tournament.

Members of the adjudication core will often leave tab-relevant decisions until the days prior to the first round or whenever it is that they can first meet with the tab team in person. This often wastes critical time and forces rushed decisions. Many considerations can instead be raised and discussed prior to the tournament. These could include:

• How to manage the feedback process. This typically benefits from foresight and pre-planning, rather than being decided on the ground. Key considerations are:
  • Who submits feedback on whom? Do trainees do so on their chairs? Do panellists do so on each other? (Presuming your tab software supports these options).
  • Is feedback mandatory? If so, how will this be enforced exactly?
  • How much weight does each adjudicator’s test or CV score have over the course of the tournament? By Round 3, or by Round 8, what proportion of an adjudicator’s score is derived from their test and what proportion is derived from their feedback?
  • Will the adjudication core tweak an adjudicator’s score to ‘artificially’ increase or decrease it to where they think it should be. For example, this could be done by adjusting a test/CV score upwards in order to compensate for bad feedback that (for whatever reason) they did not think was reliable or fair? Depending on your adjudication core’s preferences and your tab software’s allowances it is not unheard of for them to maintain full manual control over scores by reading/processing feedback results but only ever manually adjusting scores as a result (rather than having it automatically adjust due to the ratings in the feedback).
  • What is the score scale going to be? What do each of those numbers represent? How will this be communicated to participants so they can score accurately and consistently?
  • What kind of questions will feedback forms ask? If using customisable printed or online forms consider how these questions be used tactically to identify key issues (say discriminatory scoring) or more easily identify people who should be promoted/demoted. While managing feedback is often a messy and subjective task, it can often be improved by being more targeted in what data it collects.
  • How will feedback be monitored, and how will this information feed back into the scores and allocations? At large tournaments it is not unusual for an adjudication core member to sit off each round to review and process feedback — there isn’t really a good stretch of available time to do so otherwise. However even if doing this note that there are communication issues to manage here, as each adjudication core member will each end up with a relatively incomplete overview of the total volume of feedback.
• If possible it’s nice to plan in advance for when the tab will be released (i.e. on the last night; the day after; etc.) as this often gets left to the last minute to be decided. Also the possibility of whether people can redact themselves from tabs should be raised, as that might be useful to inform participants of during online registration or tournament briefings. In a similar fashion, some adjudication cores might also want to limit speaker tabs to only a certain number of places, particularly at novice-centric tournaments.
• How to handle conflict collection; see the following section.
• How to handle the submission of scoresheets and feedback, primarily in terms of which parts of the process should be done online and offline. Some adjudication cores will have strong thoughts here; others will happily follow whatever you recommend. Key considerations:
  • Paper-based feedback is much more taxing to enter than paper-based scoresheets — typically there is much more of it; it asks for a greater variety of data; and it is submitted at inconsistent times. The one advantage is that it is easier to make feedback mandatory with paper, as you can ensure all teams and adjudicators have done so prior to leaving the room. Thus, in most cases, a good online feedback system is much more preferable than paper. If using paper be aware that you will need a lot of volunteers to ensure the feedback is collected promptly. If internet or smartphone access is limited at your tournament it is probably best to accommodate both paper-based and online methods.
  • The consequences of having incorrect or missing ballots are much more severe than for feedback. As such major tournaments use paper ballots in some form as the final stage in a checking process to ensure that the results of a debate are definitely correct — adjudicators will always make mistakes and while digital ballots can catch/prevent some types of error (i.e. a low point win) they can’t catch others (assigning the wrong scores to the wrong speaker, nominating the wrong winning team, etc.). Assuming your software supports both options, the choice is thus whether to use a hybrid approach (online submission followed by paper verification) or to rely entirely on paper. A fully-paper based approach will be simpler for both yourself and adjudicators, and can be almost as efficient if you have a sufficient number of volunteers. In contrast, a hybrid approach will be potentially much faster if you are short of volunteers and if you expect that almost all adjudicators will have access to the internet, a smartphone, and are capable of following instructions.

Note

In some circuits, and when using some particular tab software, tournaments might run a ‘dual tab’ where there is a second, independent, version of the tab software and database into which all data is also entered. From what we understand this performs a dual role, as both a backup system that can take over from the main one (say if internet access drops) and as a way of verifying ballot data (by comparing draws or databases between software rather than having a two-step entry process operating for a single tab). This practice seems obsolete when working with modern web-based tab software that is capable of backing up and restoring to an offline system, but we would like to hear your feedback if you think that is not the case.

Conflicts/Clashes (registration/equity/adjudication core)

• There should always be a single means of collecting conflicts (i.e. a single Google Sheet/Form) and all conflicts should go through it. Because the nature of this data is sensitive and evolving, there must be a single location where it can be easily captured and verified as having been entered into the tab. Conflicts data should never be spread across a loose collection of emails/personal messages/spreadsheets; otherwise keeping track and knowing which ones have been entered into the system will be painful and error prone. Get in touch in with equity and registration in advance and make it clear that they should not make their own conflicts form; or if they’ve already made one, make sure you adopt it and have access/control of it.
• Conflicts should, ideally, only be collected after a participants list has been published and requests for people to nominate conflicts should also be sent out as few times as possible. Most people will only fill this form in once, so it is vital that when asked to nominate conflicts they have as much information as they need to do so comprehensively. Without a public and reasonably-complete participants list people will either nominate conflicts that are not present (wasting your time in cross-referencing data) or not realise someone is present and raise the conflict at a latter, less opportune time.
• In some circuits only adjudicators are allowed to nominate conflicts because of the risk of teams using conflicts ‘tactically’ to block adjudicators that they think are terrible judges. However, having teams nominate conflicts can be useful: adjudicators may overlook a conflict or there may be equity-based reasons that a conflict is non-symmetrical. This trade-off can be handled in two ways:
  • Not allow teams to nominate conflicts during registration; but allow them to approach equity teams before, or during, the tournament to identify the conflict. Equity can then raise the issue with the tab team and adjudication core and it can be added to the tab.
  • Allow teams to nominate conflicts during registration; but have the adjudication core review the data for ‘tactical’ conflicts. These are usually relatively easily identified, although can be overlooked if the adjudication core does not know the participants or their region/circuit well. The adjudication core can then override the conflict, discuss it with the teams, or raise it with equity. However, if going down this route, the tab team should discuss with the adjudication core how to manage this process well-ahead of the tournament, and ensure they actually do review the conflicts prior to the first round — otherwise it will likely surface during an allocation and become a major distraction during a critical time period.
• As mentioned in the previous section, the adjudication core (possibly with equity) should provide some degree of guidance about what kinds of debating-related conflicts should be provided. People should be able to self-define what constitutes a conflict, but there are circumstances where they are overly cautious and can be reassured that it is not necessary. The opposite problem may occur also, where many people may have a very high bar for what defines a conflict which could lead to perceptions of bias from other participants.
• Generally, it is preferable that each form nominates a single conflict, and people are asked to re-submit for each conflict they are adding.
  • To save you some hassle the conflict form should make this very clear (i.e. that one conflict = one submission; ensure the field labels reinforce this)
  • The conflict form should also make clear that you shouldn’t use the form if you don’t have any conflicts (i.e. people will submit ‘None’, ‘None’ etc)
  • The conflicts form should also make clear that adjudicator’s don’t need to submit a conflict for their current institution and that team’s don’t need to submit conflicts for adjudicators from their current institution.
• In poorly-structured conflict forms, identifying exactly who is doing the conflicting and who is being conflicted is a nightmare. You want to structure the questions to minimise this ambiguity. A form should definitely ask:
  • Who are you (the conflict-specifier)?
  • Are you a team or an adjudicator?
  • Which institution are you from?
  • If part of a team, which team are you in?
  • Who are you conflicting?
  • Are they a team or an adjudicator?
  • Which institution are they from?
  • If they are in a team, which team is it?
  • Have previously attended any other institutions; or have other reasons to conflict entire institutions? If so, specify those institutions.
• Note that this last question can be tricky to deal with; good tab software will let you conflict an adjudicator from an institution other than their own, but it is harder to mark an individual team as having members previously attending another institution. These circumstances are rare and typically very ‘soft’ conflicts but are probably best handled by creating individual conflicts between that team and adjudicators from the previous institution in question.
• Adjudication core members will often not nominate their own conflicts; presuming that they will notice and correct them during allocations. They often forget or overlook this. Their conflicts should be entered as per normal.

Scheduling (convenors / venue organisers)

One of the easiest ways to have things run late is to set an unrealistic schedule. As much as possible the timing allocated to rounds (inclusive of events such as lunch or committee forums) should conform to an even distribution of how long it takes to process results and create a draw/allocation — you don’t want to be in a position where particular rounds have too much time and others too little time to spend on allocations and other crucial tasks. This is something that should definitely be working on in conjunction with convenors and other critical parties before they lock down timing details with food suppliers or the operators of the debating venues.

Note also that in most circumstances it is preferable to create a draw and allocation for the first day of the next round at the night before. This time should be built in to the schedule of the previous day, and raised with the adjudication core so they don’t expect to be able to immediately depart after the day’s rounds are done.

Below is the time taken within each round at Australs 2017. For context, this was neither a particular efficiently or inefficiently tabbed tournament. Notable details:

• The tournament was ~40 rooms each round and had access to 3-6 runners and data enterers. Paper ballots were pre-printed and distributed by runners to rooms prior to the debates starting, then collected sometime after the 15 minute deliberation period. Feedback was submitted online. At Australs all adjudicators (excluding trainees) submit their own ballots.
• The adjudication core were neither particular slow nor fast in allocating adjudicators compared to other adjudication cores. At Australs most adjudication cores will create allocations by using first running an automatic allocation then extensively tweak the results.
• There were no serious issues that delayed the tabbing of any particular round beyond the routine and expected issues of last-minute draw changes, adjudicators producing incomprehensible ballots, etc.
• Whilst the tab ran relatively quickly, there were minor delays because of mismatches between the planned schedule and the optimal schedule from a tab perspective.
• A round at Australs takes around 2 hours from a debater’s perspective: 30m of prep, ~60m for a debate, ~15m for deliberation, and ~15m for the oral adjudication and feedback.
• We didn’t note the timing of data-entry in Round 8 as there was no time pressure. After data entry was finished, finalising and double-checking the breaks took through to ~7-8pm.

Day	One			Two			Three
Round	1	2	3	4	5	6	7	8
Draw generated	Night prior*	12:43	16:12	19:17*	12:05	15:46	19:10*	12:07
Allocation finished	Night prior*	13:17 +34m	16:36 +24m	20:28* +71m	12:58 +53m	16:24 +38m	21:30* +140m	13:25 +78m
Motions released	09:28	13:50 +33m	16:47 +11m	09:22	13:14 +16m	16:40 +16m	9:30	14:18 +53m
First ballot received	11:51 +143m	15:46 +116m	18:52 +125m	11:18 +116m	15:13 +119m	18:40 +120m	11:35 +125m	?
Last ballot confirmed	12:38 +47m	16:07 +21m	19:15 +23m	12:05 +47m	15:44 +31m	19:09 +29m	12:06 +31m	?

Tab Setup

Setting up a tab site is the most technically challenging (or at least annoying) part of tabbing. It is where you need to reconcile large amounts of data and configure a variety of settings to ensure everything will run without issues during rounds. While this is often done a day or two before the tournament, ideally you should look to do as much as possible in the week or two beforehand where there is much less time pressure.

Importing data: workflow

• First check with registration people if their data is complete, and if not who is missing. If it’s only a few people it’s viable (for tab purposes) to use place-holders for them, as long as you remember to follow up and edit their data manually later.
• Familiarise yourself with the different methods for importing data into your tabbing program. Typically, these include options for bulk-importing spreadsheets, for adding information piece-by-piece through a graphical interface, or a hybrid systems. Depending on your tabbing software it may be easiest to first setup your tournament on a local copy of the tab (where it will be faster to rectify mistakes) and transfer the data to the live site when everything is mostly complete.

Note

If you are using Tabbycat our spreadsheet importer is definitely easiest to use on a local copy; however using the visual importer is perfectly viable for larger tournaments if you are not comfortable with the command line. When using the spreadsheet importer note that it will likely take several iterations to get the data to import cleanly as there will typically be small mismatches in speaker/institution names and the like.

• If the tournament (or the host society) has their own domain name and your tab software is self-hosted consider whether you want to setup the tab site on their domain so that the URL is nicer and/or easier to type.

Note

If you are using Tabbycat, and deploying to Heroku, be sure to read our documentation about the size of Postgres database your tournament will require. Setting up the correct size of database from the start is the best way to go, as transferring information at a later stage is a hassle and could delay the tab at inopportune times.

Importing data: regions/societies

• Societies will often have special names that they like to use in draws (that are not the same as their institution’s name or acronym). These can be gathered from institutional reps or from prior tabs. When in doubt err on the colloquial / most recognisable name; particularly for formats where teams need to find each other prior to the debate.
• If your tabbing software has methods for assigning region information to teams and adjudicators (for diversity purposes) determine with the adjudication core the types of regions that will be used.

Importing data: participants

• Check you have emails/phone numbers included in your data that will be imported (presuming your tabbing software supports this) there are useful to have on hand later for either emailing out information or quickly following up errant adjudicators.
• Often, the easiest way to prepare registration data for tab imports is to create new tabs in the registration spreadsheet, and use referencing to automatically order and arrange their data into the format your tab software wants. If the registration data changes significantly this will also make it easier to re-import things.
• Often some adjudicators, typically local independents, may not be available for all rounds. Try and find out who this affects and when; once data has been imported you can pre-check these adjudicators in and out of rounds (if your tab software supports this; otherwise note it for later).
• Remember that the swing team(s) probably also need to be imported into the tab.

Data import: rooms

• Ideally you want not just a list of rooms, but also of their types and categories — i.e. what building a room is in and/or it will be coded so that participants can find it.
• You want to know if access to some rooms is conditional; i.e. if some rooms are only available for some rounds. Again, if your tab software supports it you can record this availability information into the system (once data is imported) otherwise you can note it for later.
• Registration should have collected information about accessibility requirements; they should be imported into your tab software (if it supports automatically matching accessibility requirements) or note for later. In general you will also want to use a similar process to ensure that members of the adjudication core are assigned rooms that are close to the tab room.
• You also want some idea of priority; that is to say if some rooms are inconvenient (and you have more rooms than you need) they should be marked as a low priority so they will be allocated only if needed. Again, this might be automatically done by your tab software or something you will need to note and manually change after each draw is made.

Data import: adjudicator test/CV scores

• Ideally the adjudication core should do this themselves as they are marking the test or scoring CVs. If they won’t, or you don’t trust them with full tab access, be prepared to do so yourself.

Data import: tab access

• Set up user accounts for the adjudication core with dummy passwords (they can change them later).
• Set up user accounts for runners/assistants with dummy passwords (they can change them later).

Note

If using Tabbycat and using online ballots or feedback with the private URLs method, participants should be emailed out their private URLs before they start travelling to arrive at the tournament (i.e. when they have a reasonable chance of checking their email). This can be done using the inbuilt pages on Tabbycat, or by importing participants data into a service such as Mailchimp.

Pre-Rounds Setup

Setting up the tab room

This is typically the first order of business, as all future pre-round setup tasks (i.e. training the adjudication core, testing printing, etc.) are better for being done in the same space that will be used throughout the rounds. Once you’re in the space there are a couple of small checks to run through before the larger question of how to arrange and use the space should be tackled:

• Check with convenors whether things can be left in the tab room overnight. If they can’t you’ll need to make plans for how to move any big items (printers; ballot stacks) to and from the tab room each day.
• Check that the internet access in the tab room is reliable.
• Check that the projector system works, both with whatever wired-in computer is in the room and when connected to your laptop.
• Check what items either yourself, or the organisers, have at hand and check if anything needs to be acquired before the next day. Critical items for tab rooms are typically:
  • An extension cord with multi box; ideally a pair of each.
  • Whiteboard markers (assuming there is a whiteboard) otherwise permanent markers and large sheets of paper (i.e. A2) can suffice.
  • Boxes. Lots of boxes. Loose ballots are a source of confusion and error, so you want some way of temporarily storing ballots as they proceed through the entering and checking process. You probably want at least three large boxes (for ballots to-enter, ballots to-check, and finished ballots) but more will be useful.
  • Spare printing ink/toner, and paper for the printer. Ideally your paper would be multi-coloured, with each colour being used for a different round. Pastel colours are ideal, and you ideally want at least three different colours so that you don’t have to repeat a colour within the same day. Be sure to calculate how many sheets you will need per round and ensure you have a generous number of spares.
  • If tabbing a format that can produce multiple ballots per-debate, staplers are essential to keep those ballots organised. Buy at least two sturdy ones.
• Non-essential, but often useful to have items:
  • Whatever dongles/adapters you need to connect your laptop to the projectors, both in the tab room and in the briefing room.
  • An Ethernet cable (or two) as a backup option if WiFi drops or is overloaded.
  • Post-it notes are a great way to temporarily mark ballots with information; typically used to indicate ballots that need correcting.
  • You’ll often need to make impromptu signs; sticky tape and/or blu-tack are good here
  • Spare pens for the people doing data entry to use
  • Trash bags for collecting rubbish as it accumulates
  • A Chrome Cast can occasionally be very useful if a projector or screen doesn’t have accessible input cables or so that you can use a projector without having your laptop tethered to a particular podium and desk.

If you haven’t already it’s a good idea to check your printing setup by printing off a bunch of generic ballots and feedback forms to have on hand if the need arises (i.e. a ballot is missing and needs to go out ASAP; or if someone can’t do feedback online and needs to do so on paper). At worst, the blank ballots you print can be used for the out-rounds. While printing these off, time how long it takes the printer to print say 25 ballots and extrapolate from that to figure out how long it will take to print the entire round’s worth of ballots. Note that if printing off a round’s ballots is relatively quick it can be useful to delay it in order to better accommodate any last-minute changes to the draw that happen post-announcement. It’s also worth thinking about how you (or at least who will) group up the printed ballots in order to distribute them to runners.

At this point you should also setup whatever process you need for managing runners and the ballot collection process. At a minimum, this should probably be a spreadsheet or a list on a whiteboard outlining the different groups of rooms with spaces to mark in which runners are delivering/collecting ballots for each location. Who is running where might change from day to day and should be kept updated. It should also have some method for contacting each runner (i.e. a cell phone number).

The question of how to arrange the actual room is one with many answers, and is obviously shaped by the peculiarities of the space itself. However there needs to be some system behind it so that people know exactly where to go and what to do when there is time pressure.

The key consideration behind this system is typically the ‘flow’ of ballots: what happens after they are brought back from runners, but before they are completely entered into the system. Think through how you want this process to operate and how the space can be arranged to make each step as smooth as possible. Considerations:

• When runners initially return a big stack of ballots, what happens? They could be transferred directly to the data-enterers to start on, but it is often useful to have preliminary checks here in order to keep the job of the data-enterers as simple as possible. These checks could include:
  • For formats with multiple ballots per-debate, you typically want to identify and staple together all the ballots from a given panel.
  • For tournaments where ballots are liable to go missing (or for when you have plenty of data-enterers and want peace of mind) it is worth using the ballot ‘check-in’ system of your tab software (if it has one) to mark off ballots as physically present in the tab room. This allows you to quickly identify which ballots are missing and begin tracking them down earlier than you would do otherwise if just waiting for the ‘to enter’ pile to be exhausted.
  • Depending on your preferences and resources, ballots could at this stage be checked for errors. This could include a basic sweep for missing information (i.e. totals) or a comprehensive sweep that includes checking math errors, ambiguous handwriting, low-point wins, etc.). While this will delay the time between ballots arriving and being entered, it will mean that you can start correcting ballots sooner, and lessens the burden on (potentially inexperienced) data-enterers to check and catch these. If you have many runners, and they are familiar with how debating scoring works, this is recommended.
• Once this preliminary step has occurred the next task is actually entering the ballots. The number of steps here is dependent on your tab software and tab settings; you might have had the ‘draft’ ballot be submitted online by chairs or you might have the whole two-step process of a ‘draft’ ballot entry and the ‘confirmed’ ballot entry taking place within the tab room. Considerations:
  • Regardless of whether you are working with a one-step or a two-step process, you want to arrange the tables where data-enterers are sitting such that their need to move is minimised. That might mean either have a central inbox of ballots to enter in the centre of the tables (such that everyone can reach it) or having multiple ‘clusters’ of enterers around boxes.
  • If work with a two-step process you want those two steps to be an active part of the spatial arrangement. That is to say, typically there will be a grouping of enterers who are working on the initial ballot entry (clustered around a box or boxes) and then a separate ‘downstream’ grouping of enterers that work on confirming/validating those entries. Depending on the size of tournament and quantity of runners, you either want it so that individuals from the first group can easily pass their ballots to the box of the second group; i.e. by reaching across the table or walking a short distance. At huge tournaments, you might want a dedicated person to transfer ballots between boxes to prevent enterers having to get up.
  • In a two-step process people may need to transfer roles, as generally you want to prioritise entry and then validation. Often this isn’t necessarily much more efficient, but if ‘rebalancing’ the roles make sure that the spaces assigned to each role can accommodate extra people, and that people physically move to occupy each role.
  • In general, you want to minimise the number of ballots that each enterer feels the need to ‘hoard’ to work through to keep the work evenly distributed. If people are taking a large number of ballots to process, at the final stages of entering some people will have a bunch to work through while others will be finished. Making it easy to collect and pass on ballots in the space itself helps cut down on this while keeping entry efficient.
  • While the exact spatial arrangement depends on your numbers and what furniture is available, a long rectangle is a good starting point as the ballot process is in general linear (check, enter, validate, finish). Typically, this might look like a series of tables in a row with enterers sitting on either side and with the various ballot boxes in the middle.
  • When ballots have finished being enter/validated there definitely should be some sort of final ‘done’ box. Take care how ballots are put here, a common source of error is people putting ballots there before they are fully finished.
  • When ballots need to be corrected you generally want to ‘extract’ them from this process and hand them off to a tab-director or assistant to chase up and collect. There should be a forethought process for managing this; and ideally a dedicated space for it to prevent ballots being lost and to make it easy to identify ongoing issues. This might look like a process of sticking a post-it note (outlining the error) to the ballot, and then pulling it from entry/validation and placing it on a desk. Ideally you also want one of the tab directors always not doing data entry so that they are immediately available to manage this process.

Training volunteers

If at all feasible you want to train that volunteers acting as runners and/or data enterers the day before the tournament starts otherwise the first round will be rough. It’s generally a good idea for this training session to generally mirror the process of running a round. It’s also generally a good idea that — even if you have enough people for dedicated runner and data-enterer roles — to train all volunteers so that they are familiar with each role and can fill in if needed. This has a couple of stages:

1. Introductions and details

• Volunteering is typically thankless and often stressful. It’s also quite a dull and mechanical process: deliver paper; collect paper; enter numbers; check numbers. Given the rather unglamorous nature of their role you want your volunteers to feel welcome and a crucial part of a wider team. When meeting everyone for the first time try and run the introductions in a non-perfunctory manner and get to know people’s background/interests and outline how valuable they are to the tournament.
• As part of this process you should, note their cell phone numbers or whatever means you will use to coordinate communication between the team.
• Figure out what will be happening during downtime and how you can make it more enjoyable. Would volunteers like to watch debates, work in the tab room, etc. Is there anything they would like during those down times (music, snacks, coffee, etc.).

2. Rooms and Running

• If runners are unfamiliar with debating in general, outline the basics of what draws are, what ballots are actually for, and what this process looks like from a debater’s perspective.
• Outline how/when the printing process occurs and who will sort/assign the ballots. Now is a good time to assign different runners to the different groups/rooms that they will be working with.
• It is critical that, as a group, you actually go to everyone one of the venue groups and identify all of the venue rooms that are listed so that everyone knows exactly where to go. This may take some time. But it is a good chance to both check those rooms actually exist and pre-identify any problems that might occur with runners and debaters finding them.
• Outline in general what happens during ballot collecting: when to do it, how to approach chairs, what do to if they are slow or delaying. You should raise the chance of chairs being belligerent and outline how they (and you) should deal with this.
• If you are having runners pre-check ballots it’s a good idea to fill out a few ‘bad’ ballots to demonstrate the kinds of checking required. If you are using any communication systems (i.e. having runners mark of buildings as ‘done’ in an online system) go through that now also.

3. Data entry and checking

• Before starting, setup logins for everyone and show them how to login. Also get an idea of what devices they will be using, or can bring, for data entry purposes. Check/ensure that they will have internet access on those devices.
• Run through this in the actual tab room; illustrating examples with actual ballots and going through the roles in the actual spots which they will occur.
• Run through how the seating/table/box arrangement works and the types of roles at different positions.
• Emphasise that in general, any ambiguities should be raised with the tab directors/assistants; i.e. that you should never guess about ballots but instead always delegate resolving issues to someone else.
• Run through the different edge cases and things to check during entry. For example Iron Person speeches, mismatched totals, entering the wrong ballot for the wrong panellist, etc (see section below). Be sure to also go through what happens when the validation step fails; i.e. when a ballot needs to be re-entered.

Training the adjudication core

Typically making the first-round’s draw and allocation is the best time to really run through how your tab software and processes work in a ‘real’ environment as well as the expectations surrounding their and your role. Generous amounts of time should be budgeted for this; it’s not uncommon for it to take up most of an evening. It’s also worth having an older tab, or a tab full of fake data handy in order to show them how, say, the feedback or allocation interfaces look like when full of data.

To kick off you should probably setup tab logins for the adjudication core as necessary, outline what kinds of access they have, and (particularly if they haven’t used your tab software before) outline broadly what pages they should and shouldn’t access. In particular, show them how to find and parse feedback as that is often the interface where they will be spending most of their time individually. As part of this tour outline (if you haven’t already) how feedback will work, as well as the means by which the adjudication core can use the tab software to keep track of feedback as it comes in. Ideally some sort of general strategy should be formed for this, so that particular people sit out rounds, or are delegated the task of catching up on feedback at other points.

Depending on how many runners you have it may be necessary, or beneficial, if the adjudication core helps out with data entry. However, if you go down this route the adjudication core need to be highly trained; they are often much more likely than volunteers (who are less self-confident and have more experience) to make errors. Whether you do or don’t do this, ensure that adjudication core members know to come to the tab room ASAP after they have finished adjudications rather than swanning around socialising or going to lunch. Draws will often be held up just by the fact that not enough adjudication core members are present to start or finish an allocation.

The first-round allocation is the last thing you want to cover. It is typically your only change to slowly and comprehensively walk the adjudication core through the allocation interface and the allocation system.

Allocation interfaces, while often complex, should be stepped through so that the adjudication core knows precisely how to operate it themselves (if needed). They should know what it can (and can’t do) and how the different features can be used and activated. For example, diversity highlights might be an optional toggle (in which case you explain how to active it, when to do so, and what it represents) or there might be parts of the interface that detail information such as a room’s liveness, energy, or bracket which should be highlighted and explained (i.e. how ‘liveness’ is determined).

Secondly, and most importantly, is outlining how the automated process of adjudicator allocation operates, and how this can be made to match the adjudication core’s preferences. Typically, you want to rely on automatic adjudicator allocations as much as possible in order to decrease the time taken to do an allocation; however every adjudication core has a different philosophy on what their perfect allocation looks like, and it is your job to try and align that ideal with what the automated system produces as much as is possible. The precursor to this is yourself knowing how your tab system allocation works: what is the relationship between a debate’s bracket (or assigned priority/energy) and the numeric ranking of the automatically generated panel? Does the software optimise panel strength for a voting majority, or across all panellists? When does the software allocate solo chairs over panels? How does it avoid conflicts? Does it have (and enforce) particular expectations for a given adjudicator’s score; or does it rely on a more relative comparison? The answers to the questions will often be dramatically different between different programs and you should know them in advance.

Most tab software will have at least some options for you to configure those automated processes — either by changing the automatic allocation’s parameters directly or by controlling the ranking and feedback systems that feed into it. The first round is the prime opportunity to configure these options so that they align as close as possible with what the priorities of the adjudication core. If your feedback ranking system is mismatched with how you expect the automatic allocation to place adjudicators, or if the distribution of adjudicators across the draw is not what you expect, the adjudication core will end up wasting significant amounts of time adjusting allocations. Even if things work well using the default settings, ensure you experiment and demonstrate the consequences of changing the settings just to show that it can be done, what the general effects are, and to see if there are even-better configurations.

Note

This process of tweaking the automatic allocation settings is one you should also revisit as the rounds progress.

How to approach diversity (typically in terms of region and gender) across an allocation in particular is something that some members of an adjudication core will not have had to consider in the context of a large tournament with time pressure or in terms of having to make explicit trade-offs. Again, you should make it clear how the software can accommodate this, and get the adjudication core to plan for how (in general) they want to approach this. Often it will form the final phase of the allocation process, and so can easily be forgotten or skipped over; or people will have different philosophies of how to approach this which are only raised at critical points.

Outline that there will usually be a trade-off between the quality of each allocations and the speed at which the tournament runs. When time is not a factor, many adjudication cores will often take an hour or more in order to create a perfect allocation; but they should know though that aiming for perfect during many rounds will break the schedule. You should try and get them to set some sort of time goal for allocations, and (during the rounds) ensure that they are aware of when they are going too fast or too slow. Depending on your personal preferences and the norms surrounding tab direction in your circuit you may want to actual enforce these time limits.

Finally, outline how you will all communicate. Again, there should be a single medium for this so that everyone knows what is going on; and this is ideally something that has been planned out beforehand with them and the organising committee. But at this point the tab team may have expanded, or there may be better options than what was being used previously. It’s also worth outlining which parts of the tab team will generally be doing what roles and where — i.e. who will be rolling the draw, who will be chasing up people, etc.

Preparing a briefing

• At large tournaments there should be some form of briefing covering ballots and feedback process, even if it is just quick one. Usually you will want to be the person to design and deliver this; other people less-familiar with the system may miss details.
• Liaise with convenors and the other people doing briefings to ensure (a) they know you’re doing one; and (b) you are not overlapping in terms of content.
• See the last section of this document for notes on what can be useful to include here

Final checks

• Check if the convenors have made a map that clearly outlines where the rooms are. Ensure it’s clear and post it to either the tab site (ideally) or somewhere like Facebook.
• Check that convenors have some sort of way-finding system in place, i.e. chalked directions or colour-coded signs. Check these colour codes match the names of your venues.
• Check that the draw types are correct for each round in the tab system.
• Check with adjudication core if/when there are secret rounds and that these are correct in the edit data base area.
• Check how the draw will be displayed and managed. Is the projector good; how big does the text size need to be? How fast is the scroll?
• If you will pre-print ballots check that you’ve set the “return ballots to” configuration setting; even if it just says “to runners”.

Managing Rounds

Once everything has been setup and everyone knows what they should do, the actual process of running each round should go smoothly. It probably won’t though. The earlier sections should have laid out what the ideal process for managing data entry and allocations, so this section will instead focus on what can go wrong and what to keep an eye out for.

Disaster scenarios

There are two broad classes of disaster scenario here. The first, and more rare case is when either internet access at the venue goes out or if a web service that your tab software depends on has an outage (for example, both Tabbie 2 and Heroku-deployed Tabbycat instances depend on Amazon Web Services). The first can at least be solved temporarily if tethering is available, but if that is not possible (or the latter case occurs) you may need to switch to using an offline copy of that tab by restoring from a backup if the outage is non-transient.

Obviously, for this to work, you should be taking regular backups using whatever mechanism your tab software allows. Key times to do so are critical events such as finishing entering a round’s data or finalising an adjudication allocation as these are especially difficult to recreate. Importantly, these backups are only useful to you if you have a downloaded copy of them; ideally download to a Dropbox or some other cloud service that will spread them across multiple computers and an online service.

Having an outage of internet access or a key web service go down to the point of having to switch to an offline tab is an exceedingly rare event, but one worth planning for at large tournaments. That is to say you should have ideally have an offline copy of your tabbing software setup on your local machine, and know how to restore a backup to it if necessary.

Backups are also useful as guards against a much more common source of error: data loss caused by user error. It is not unheard of for even experienced tab directors (or inexperienced adjudication core members) to accidentally delete an entire allocation, delete a round, or some other form of destructive action that would require a lot of work to redo. Taking backups at key points, and knowing how to restore them (to the online copy of the tab) is a useful — and occasionally essential — skill.

Note

The much more common source of a major tab disruption is a major user-error or a bug within your tab software itself. Fixing these will be highly-context dependent and the best way you can prepare for them is to know your tab software well enough to understand what might have caused it or be able to contact someone else who does. That said, having backups on hand can also allow you to restore your database to before the bug or user-error occurred and try to proceed without re-triggering it.

Expected problems

Incorrect ballots are an inevitable tragedy. Many more optimistic tab directors will imagine that these can be prevented through sufficiently detailed briefings, recurring public shamings, or fool-proof ballot designs. While these might help in cutting down the number of errors, eliminating them entirely seems to be an unachievable goal. Note that this is particularly true at international tournaments and/or at tournaments that draw participants from circuits which have more than one predominant format.

While debaters as a whole display astonishing levels of innovation in discovering new ways to incorrectly fill in a ballot, there are a couple of broad cases that you should look out for an prepare people to deal with:

1. Not adding up score correctly. Pretty much everyone who does this will note that this is the first time that it has ever happened to them.
2. Omitting some information. Most common are not filling in total scores, the nominating winner, or the margin. Having omitted an entire team’s scores or speaker names is not uncommon.
3. Scores that are outside the range.
4. Low-point wins, or tied-point wins. Typically occurs in conjunction with (1).
5. Poor handwriting rendering numbers illegible. While one could ‘guess’ whether a number is in fact a 6 or a 5 based on a team’s total score, doing so is dangerous as it assumes that the person hasn’t also done (1).
6. ‘Correcting’ information in an ambiguous way. For example, using arrows to swap a speaker’s order (which is typically circular/ambiguous) or drawing numbers over other numbers in a way that makes it unclear which is the original and which is the replacement.
7. Ballots just going entirely missing because either a runner missed the room, the chair forgot to return it, or the chair just left it in the room.

Ballots aside, there are a number of other common occurrences that will necessitate changes to the drawn and allocations:

1. Teams will not turn up to debates, or turn up to debates extremely late. In both cases they will often not notifying anyone. Aside from needing to swap in a swing team in their place in the draw, it’s worth keeping in mind that the necessity of a swing team might not be known until right when debates are about to start (which can lead to issues if you assume trainees or runners will be filling up the ‘spare’ swing team).
2. Adjudicators will also go missing. As with teams this can usually be caught during roll call; but might also not be known up until debates start. If the adjudication core is available they can make adjustments, but often you will need to make a call as to whether to form an even-sized panel or to redistribute adjudicators from elsewhere.
3. When a draw is released there will often be conflicts that were unknown to the tab system, and will necessitate making changes to the draw post-release. It’s important that when making these changes you keep a clear record of what needs to change (if there are multiple swaps needed it can get tricky to keep track of) and ensure that all parties involved know about where they are being swapped to.

Ongoing checks

You will have a decent amount of downtime during rounds when debates are happening. A couple of things its worth keeping an eye on during that time:

• Ensuring your backups have been taken and downloaded.
• Ensuring the tab room isn’t devolving into mess.
• If you can be bothered (and if no adjudication core member is doing so) reviewing feedback for critical issues (i.e. comments highlighting severe issues, or chairs getting very low scores) is a good way to be useful. If using paper-based feedback this can look like physically separating out these feedback forms for the attention of the adjudication core; while if using online feedback systems you may want to keep a collection of browser tabs to show.
• Chasing up the language committee (if one exists for this tournament) to confirm which teams are in which category and what their break preferences are (if multiple breaks are not allowed). You want to have this information confirmed as soon as possible as it becomes of critical value to allocations once the draw starts segmenting into live/dead rooms.
• Reviewing how efficiently things are running and whether there are any bottlenecks that can be better addressed in the next round. It’s generally a good idea to (on a whiteboard or a spreadsheet) keep track of how long each stage of a round is taking (running, data-entry, allocation) and what (if anything) is causing delays.

Note

If hosting Tabbycat on Heroku keep an eye on the metrics section of the dashboard area, noting if there are ‘timeout errors’ and what the average response times are. Adding more dynos should help with both.

Breaks and Break Rounds

Generating the adjudicator’s break

Determining the adjudicator break generally involves a complex set of considerations rather than strictly ranking based on feedback. As such most adjudication cores will use whiteboards or Google docs to draft and discuss the possible options. One thing to note here is that breaking adjudicators will need to be marked as such in the tab at some point (both so they can be on future draws, and for publication) so you want to be careful that the tab is the final source of authority here — it is easy for information to get out of sync between what the adjudication core is using to draft the break and the system.

When the adjudication core is determining the break ensure that they have an idea of the quantity of adjudicators needed (breaking too few or too many will cause issues) and whether there are any special considerations (such as having conflicts with large portions of the draw, or leaving at a given point) that involve a specific adjudicator being considered.

Generating the team break

Before doing so in an automated fashion, first check in your tab software whether all teams are assigned to the right break categories. Depending on whether your software supports multiple formats you probably also want to check that each break category is using the right ‘rule’ specified by the tournament (i.e. a WUDC- or Australs- compliant break ranking). Also double check the break size itself is correct in the software.

Hopefully the automated system will generate a correct break, but this should always be checked against what you’d expect the results to be from standings. Note also that there are cases, such as when a team has to leave, or when teams are or are not double-breaking, that mean the automated break results need to be overridden (typically in Tabbycat you would add a marker or note to include their ranking, but exclude them from having a break rank).

Announcing the break

Mistakes are made surprisingly often during results announcements. Again, this is often a problem with incomplete or out of sync data, where print-outs, slides, or the tab site itself might not reflect (for example) last minute changes about breaks or have potentially mixed up teams or adjudicators with similar names. Things that can help:

• Have a single source for what is being read out — i.e. a printed list (recommended) or the tab site itself — but don’t mix and match. If making slides (often a good idea for large/crowded venues) copy the data from the canonical source being announced.
• Double check what is being read out against the tab site, and/or whatever draft lists were used to determine the adjudicator’s break. Verify with the adjudication core that everyone who should be there is, and that nobody is missing.
• Clarify what information should be on the print-outs and the general order in which things are read. For example, it might be easy to omit breaking adjudicator’s institutions, to use ambiguous abbreviations over full institution names, or to have an inconsistent approach to how the information is read (i.e. whether it is read as wins then team points then team name).
• Without revealing any details try and get at least some guidance on how to pronounce names that people are not familiar with pronounce.
• Have backup copies of whatever is being read from and clarify who is reading off what portions.
• Try to publish the break list on the tab website (or via some other online method) shortly after it is announced in order to minimise the chance of misinformation spreading.

Managing the out-rounds

Out-rounds are generally under less time pressure and can be managed by just one or two members of the tab team. However, they tend to be run in a more haphazard fashion, so there are a couple of things to keep on top of:

• You should keep track of which adjudicators have or have not been used throughout the finals allocations. It is easy for adjudication cores to forget to allocate someone and have to either drop them or promote them beyond what they had originally intended.
• It is very easy for ballots to get lost in break rounds as chairs have less defined roles and processes in what they do with their ballots. While having correct speaker scores correctly entered for break rounds isn’t a strict necessity, it is nice to have and the alternative (using fake speaks just to record the winner) can cause confusion. Closely manage distributing ballots to the chairs and collecting them as soon as possible afterwards; especially if there is any time pressure. Generally it is not worth printing off per-debate ballots; just print a stack of generic ballots at the start of the out-rounds and distribute as needed.
• You should know, in addition to when the break rounds are, when the results announcements are. Often these announcements are saved (for suspense or logistics reasons) until particular points of time (i.e. until the evening social; or until other out-rounds are finished). Obviously it’s important not to accidentally release results; but often convenors and the adjudication core will often have different ideas about when results are meant to be released.

Note

If using Tabbycat to manage out-rounds with multiple break categories, note that the round progression is no longer strictly linear. So be careful with when/if results are released online and note that often you can’t rely on online interface to release draws publicly.

Preparing for tab release

At some point, if you haven’t already, have a discussion with the adjudication core about when the tab itself will be released and what data will be released. Well before the tab is due to be released you want to check that anonymisations and any speaker flags (i.e. Novice, ESL) are up to date in your tab software.

Managing the tab release

Almost there!

If hosting Tabbycat on Heroku it’s worth increasing the resources available to the server for the ~12 hour period following tab release; it’s by far the most concentrated burst of traffic the site will receive. Because Heroku bills by the hour, even going to a relatively expensive option, such as performance dynos with auto-scaling, will be very cheap if run just for this period. That said the site should be relatively resilient even in the face of large amounts of traffic; even running with the most basic resources allocated, at worst pages will be temporarily slow or not load.

To get an idea of how the site is performing in the Heroku dashboard keep an eye on the average request time number and adjust the number of dynos to try and keep it under say two seconds; ideally just one. When you first turn on the tab release settings, make sure you go through and load every page before announcing it to the public, doing so will trigger the caching mechanism that means potentially complex pages (say the speaker tab) don’t need to be calculated from scratch each time someone loads the page.

Post-tournament

Once you have sufficiently recovered, consider writing up and sharing a post-script about how things went; noting things that did or didn’t go well. Next year’s tab directors would certainly appreciate it, and it would be great to see this kind of knowledge spread more widely. The developers of your tab software would also appreciate hearing your feedback; particularly if there were issues that could have been prevented or ameliorated by the software itself.

Appendix: Briefing Notes

This is a very loose, but not exhaustive, collection of things that are useful to communicate to speakers and adjudicators in a tab briefing. While briefing fatigue is real, having clear expectations about how things like ballots and feedback work are highly valuable uses of the tournament’s time if they can at all help cut down the kinds of problems that delay the tab.

How feedback works

• Is it online, or offline? If online did people receive links? What do they do if they have lost it?
• Is feedback mandatory? What accountability mechanisms are there? Will you publish the shame list online or raise it in between rounds?
• Who will be submitting feedback on who? Do trainees do so?
• Remind teams that only one of their feedbacks count; they should coordinate who is doing it.
• What is the feedback scale? What does it correspond to? Common sources of confusion:
  • Feedback scales are not like Uber. You do not get five stars for being adequate and generic.
  • Feedback scales are not relative to position; it is an absolute scale. That is to say, if your trainee was good, they probably do not deserve the highest rating; they get whatever rating indicates they should be a panellist or low-chair.
  • Consider accompanying the score/scale with a statement characterising how these numbers correspond to positions - e.g. a 4.0 means ‘should continue on good panels, should chair low rooms’
• If using online submission options, what should people without phones or internet access do?

How ballots work

This part of the presentation will be condescending. It is also necessary. The two causes of delays in the draw running late, and thus the tournament running late are (1) people not filling out ballots correctly or (2) people’s ballots going missing. Emphasise that this should be taken seriously; minutes spent chasing bad ballots are often minutes that delay every single person at the tournament from doing what they are actually here to do. You should highlight, ideally with illustrated examples:

• Which parts of the ballot must be filled in; people will often overlook margins, or special fields such as motion vetoes.
• That people must specify the full names of speakers; not nicknames or just-first names. Often names will be written poorly or have ambiguities (i.e. two speakers on a team called James) and having the full name is the only way to resolve it.
• That people should not draw arrows to swap the order of speakers as these are impossible to decipher. Here, and in other areas, always cross-out information clearly and write it again rather than using arrows or drawing over what is there.
• That people should try and write numbers in a manner that makes them crystal clear. Put cross-bars in 7s; bases on 1’s. Make 8’s actually look like two circles. If people know they have poor handwriting maybe consider writing the literal words — seventy-one below the numbers.
• That for styles that do not have a single ballot for a panel, reiterate that everyone fills in their own ballots. At Australs, if this isn’t made absolutely clear someone will average their panels ballots in order to try and ‘help’ you.
• That runners do not fill out ballots. In BP, remind them that only chairs should fill out ballots (i.e. it cannot be deputised to a wing). In formats with individual ballots, remind chairs to make sure their wings have actually filled out a ballot, and get them to check for errors or ambiguities.
• That everyone is bad at math. People who think they are good at math just haven’t messed up their ballot yet. Emphasize that people should always use their phone’s calculators to check totals. At typical tournaments using exclusively paper ballots math errors happen multiple times a round, almost every round.
• How long people have to fill out their ballots. Suggest that chairs actually keep track of this time during a stopwatch, and start moving towards critical steps (i.e. scoring) well before the time is up, not once it is up.
• Outline what chairs should do to return ballots. If ballots are being run by runners, outline what they should do if a runner doesn’t appear. If they are not being run by runners remind people that returning ballots should be there number one priority, over say giving a lengthy adjudication or team feedback. Or getting lunch.
• Remind people to be nice to runners and that being mean to runners will have serious consequences.
• Remind people that the tab team and adjudication core will not, except for absolutely exceptional circumstances, accept photos or messaged descriptions of ballots; that all results must be on paper and handled in the same manner. The adjudication core should also be reminded of this.

How to locate the tab room

People should know how to get to the tab room, either to raise issues with the adjudication core or to correct ballot errors. Make it crystal clear where it is and how to get there. Also ensure people know not to barge in; that they should knock and wait.

Clearly communicate the contact details of the tab directors and get people to take them down. In most cases you do not want people going through convenors or the adjudication core for any tab-related issues.

Misc

Now is a good time to encourage people to consider getting involved with tabbing and tab-development. Emphasize that both do not necessarily require technical skills and that tabbers are (or should be) open to feedback and ideas from the wider community. Tell people to come find you and chat if they are interested and put up a link to the Facebook tabbing group.

If you appreciated this guide we’d appreciate a slide promoting Timekept and Debatekeeper. This would also be a good point to remind people that their timekeeping apps shouldn’t be making noise unless they have been explicitly assigned to keep time by the chair.

Tab Software Comparisons

If you’re reading this, you’re probably interested in using Tabbycat, and wondering how it compares to other options. Perhaps you’re a long-time user of another tab system, and wondering what Tabbycat can do better. This page is our effort to help answer this. Tabbycat’s been around since 2010, but since BP support is a recent addition (2017), we thought it would be useful to outline the differences between Tabbycat and other BP software.

Obviously, this page is written by the developers of Tabbycat, and naturally, we have our biases. But rarely is there a single best option for everyone and every situation: different tab programs imagine the tabbing process in a different ways and have made unique trade-offs in their development process and design decisions. So we’ve tried to be as fair and accurate as we can, and we’ve consulted experienced tab directors (other than us!) and chief adjudicators to help provide a balanced overview.

At present, this guide just focuses on the major options available for the British Parliamentary format, although we’d like to expand this to incorporate the other formats that Tabbycat supports at some point in the future. As with all of our documentation, the source for this page is on GitHub, and we welcome feedback and contributions.

On feature lists

In the first draft of this document, we had a table that listed every feature we could think of, along with which software does and doesn’t support it. This ended up not being a great idea, for a couple of reasons.

Firstly, the largest feature disparities are for relatively niche features. All of the software discussed can do the basics necessary to run a tournament: generate draws, allocate adjudicators, enter results, etc. As a result, we will — like a good whip speech — be comparative and note key feature disparities when discussing each alternative software directly.

Secondly, we felt that the ‘checklist’ approach to comparing tab software would do a disservice to the reasons you would actually choose one software over another. Except where a niche capability is essential, raw technical specifications rarely define the experience of using a product such as a phone, a car, or indeed, tabbing software. With Tabbycat, we’ve spent eight years continuously refining the tabbing workflow and smoothing out rough edges, and we believe you’ll find the result extremely user-friendly and robust. As always, the best way to check this out is by setting up a demo site and taking it for a spin!

Comparison with Tabbie2

Centralised site vs individual sites

Tabbie2 and Tabbycat are both internet-based systems. Tabbie2 hosts all tournaments on a single site. However, when using Tabbycat, each tournament or organisation sets up its own site. Each model has its advantages and disadvantages in different areas:

User identification. Tabbie2’s centralised model allows for site-wide user accounts for all tournament participants. This means that they can use the same login information for all tournaments, and perform tasks such as submitting ballots and feedback through that unified account. If you’re in an established circuit, most of your participants probably already have user accounts which are identified and collected (via e-mail addresses) during registration. If you’re in a newer circuit, or one where Tabbie2 is rarely used, most of your participants will probably need to create an account — a process which Tabbie2 handles by e-mailing them a request to do so when that person is added to your tournament.

In Tabbycat’s decentralised model, there is no persistent ‘account’ for tournament participants on each tab site or across different tab sites. Indeed, the only people who can log in to the site are those who have been given accounts by the tab director, such as tab staff and members of the adjudication core.

For secure e-ballot and e-feedback submissions, Tabbycat assigns a “private URL” to each adjudicator or team. This is essentially a password that allows a participant to only submit data that they should have access to in that specific tournament. This means participants don’t need user accounts and you don’t need to collect user account information; however if your tournament uses e-ballots or e-feedback you will need to distribute those private URLs to participants. Tabbycat can e-mail these to participants for you, or print them to give them to participants, or you could distribute the URLs using your own means.

Control over data. Some participant information in Tabbie2 is shared between tournaments, like their names and conflicts (discussed below). This means participants can manage it directly through their user accounts, without needing to go through you. On the other hand, this requires your participants to co-operate in keeping their accounts up to date, and to provide the correct e-mail address during registration (you’d be surprised how many don’t). Furthermore, participants may look to you for assistance, and your ability to help is limited to directing them through Tabbie2 channels—easy enough if they forget their password, but not so much if they forget their account’s e-mail address.

Because each Tabbycat site is its own, you’ll need to collect and import all participant details yourself. This might seem like more to do, but it also means there’s no need to match your data to existing accounts, which can be time-consuming and prone to participant error. It also means you can freely change data, for example, to correct a participant’s name or institution, or to add data like conflicts on an ad-hoc basis.

Data privacy. Conflicts are typically entered into the tab, and are sensitive information. Tabbie2’s centralisation allows for conflicts to be self-nominated by users and stored in their user accounts. This, in theory, saves the need for users to report conflicts to tab directors and other tournament staff. In practice, however, only special “super” users on Tabbie2 have access to the stored conflicts of users (otherwise anyone could access a user’s conflicts by creating a new tournament and adding that user as a participant), so many tournaments need to collect this information from participants anyway.

Tabbycat’s decentralised model means that no-one will have access to conflict information except for the tab staff of each individual instance of Tabbycat. Unlike Tabbie2, Tabbycat’s developers do not have any access to your tournament’s data — conflicts or otherwise. However, to help us continually improve the software, Tabbycat does send error reports to its developers if there is a serious bug or crash in the code, which could potentially contain confidential information depending on which page triggered the report. As a result of Tabbycat’s decentralised data storage, each tournament does need to collect and enter conflicts as part of their registration process.

When things go wrong. In our view, this is probably the most important factor. Obviously, we all hope you never have to fix things. But no software is perfect, and software developed by volunteers in their spare time (as both Tabbie2 and Tabbycat are) is especially imperfect. On occasion, glitches or edge cases occur, and fixing them requires you to directly edit the offending data in the database. Being able to do this without assistance can be the difference between a delay of minutes and a delay of hours.

In Tabbycat, because it’s your site, you have full control of the database, and can edit it through Tabbycat’s “Edit Database” area. This allows you to fix things (or break things, if you’re not careful!). Tabbie2’s centralisation prevents this—for obvious reasons, only Tabbie2’s developers have direct database access, which makes their intervention necessary if direct database access is required to resolve a problem.

Running your tournament

Tabbie2 and Tabbycat have broadly similar workflows for running rounds; at least on paper. Key differences are discussed below:

Data import. Tabbie2 takes CSV files for import. Tabbycat has a CSV file importer, but it’s (for now) only accessible through a command-line interface and is only expected to be used for large tournaments by experienced tab directors. As a more user-friendly alternative, Tabbycat also has an import wizard that’s designed to make it easy to copy and paste CSV data. This works well for small and medium scale tournaments, but is cumbersome for large ones.

Public interface. Tabbycat can optionally publish the entire draw, as well as current team point standings and results of previous rounds, online. Tabbie2 shows to a logged-in user information about the debate that user is in for that round, but doesn’t allow people to check up on people who are not themselves.

Position rotation. Tabbie2 uses an algorithm known as the “Silver Line algorithm”, which keeps swapping pairs of teams until no further improvement is found. Because it stops at any ‘local optimum’, this method isn’t guaranteed to be the best possible distribution of positions, and for large tournaments it often isn’t. Tabbycat instead uses the Hungarian algorithm, an well-known algorithm that finds the (globally) optimal allocation of positions. (One might describe this algorithm, in technical terms, as ‘powerful’.) Tabbycat also produces a position balance report, so that in every round you can see which teams have unbalanced position histories.

Venue allocations. Both Tabbie2 and Tabbycat allow for debate venues to be automatically assigned and manually edited. Tabbycat also allows you to specify ‘venue constraints’ that can automatically match particular participants with their accessibility requirements, or alternatively allow for tournament staff, such as a convenor or chief adjudicator, to be allocated rooms close to the briefing hall or tab room.

Ballot entry. Both Tabbie2 and Tabbycat support entering ballots online (‘e-ballots’) and entering ballots from paper from the tab room. Tabbie2 was built with e-ballots in mind, while Tabbycat was originally built for tab room staff, and the ballot entry paradigms reflect that. Both are flexible, just a little different—the best way to understand the difference is to try a demo of each. Also, Tabbycat takes note of the order in which speakers in a team spoke (i.e. who was PM and who was DPM), whereas Tabbie2 just records scores.

As discussed earlier in User identification; Tabbie2’s e-ballots are tied to unified user accounts, whereas Tabbycat’s e-ballots are tied to per-tournament and per-adjudicator ‘private URLs’.

Break and speaker categories. Tabbie2 has ESL, EFL and novice markers, which you can enable in a tournament’s settings. Tabbycat supports user-defined break and speaker categories, so if your tournament has ESL, EFL, novice or any other form of category, you can define and customise those categories as needed.

Adjudicator allocation algorithm. Both Tabbie2 and Tabbycat use an algorithm to recommend an initial allocation of adjudicators to debates. In principle, they both work by assigning “costs” to allocations, and trying to find the minimum-cost assignment. Some notable differences:

• Tabbie2 uses simulated annealing, which is not guaranteed to be optimal and technically needs to be tuned to be effective (which you’re probably not doing). Tabbycat uses the Hungarian algorithm, which guarantees an optimal solution.
• On the other hand, the Hungarian algorithm can’t account for relationships between adjudicators on a panel, so adjudicator-adjudicator conflicts aren’t considered by Tabbycat’s algorithm (though they are highlighted in the interface).
• Tabbycat’s cost function is simpler and more naive. On the other hand, Tabbie2’s is more complicated and can be rather opaque (even if you read its source code).
• Tabbie2 allows for single-gender panels to be charged an additional cost. Tabbycat’s algorithm doesn’t, but the interface does provide a way to easily check for this visually.
• Tabbie2 automatically calculates the importance of a room based on its bracket (team points). In Tabbycat, debate importance is configurable, allowing the adjudication core to specify which rooms are the most important, on a five-point scale. This allows more flexibility in directing the auto-allocator, by (for example) allowing you to prioritise live rooms over safe rooms to the degree you desire, but it also means you have to set the prioritisation yourself.

Adjudicator allocation interface. While both interfaces use drag and drop interactions, and allow for color highlights to help identify adjudicators by gender, region, and feedback rating, Tabbycat’s allocation interface was designed to be usable on both small screens and projectors, and has a number of extra features that can help inform allocations. These features include:

• Clashes are shown directly in the interface when they apply, but dragging an adjudicator will also show you the potential conflicts that would occur if they were relocated in a new panel. This can make it much easier to avoid creating new clashes when shifting adjudicators around the draw.
• ‘History’ conflicts (where an adjudicator has seen a team before, or previously was on a panel with another judge) are displayed so they can be avoided.
• Each adjudicator is present as occupying a particular position (chair, panellist, trainee) rather than having those positions calculated automatically.
• Chairs can be ‘swapped’ by dragging adjudicators on top of each other, and an ‘unallocated’ area can be used to view and store adjudicators that have not been allocated.

Shadow draws. Tabbie2 allows you to create ‘shadow panels’ of adjudicators that can be applied to a draft draw prior to the generation of the real draw. For very large tournaments this can be a valuable method of front-loading some of the allocation process and reducing time pressure. Tabbycat does not have an equivalent feature or method, although one is planned.

Adjudicator feedback customisation. Both Tabbie2 and Tabbycat have built-in adjudicator feedback forms, and allow you to specify the questions on the feedback form. Notable differences:

• Setting up questions is painless on neither system. Tabbycat requires you to use the Edit Database area; Tabbie2 makes you click through a slightly more opaque maze of pages and forms.
• Tabbycat allows for a richer range of types of questions than Tabbie2 does.
• Tabbie2 allows you to specify different questionnaires for team-on-chair, chair-on-panellist and panellist-on-chair. Tabbycat only differentiates between team-on-adjudicator and adjudicator-on-adjudicator.
• Tabbycat gives you more control over who is expected to submit feedback on whom; e.g. whether teams submit on panellists, and whether panellists submit on each other. In Tabbie2, you can effect this with blank questionnaires, but only for the three options listed above.
• Tabbycat can, optionally, automatically incorporate feedback into adjudicator scores using a naive weighted average with the adjudicator test score. This can be disabled by simply setting feedback weight to zero, as some adjudication cores prefer. Tabbie2 has no ability to automatically incorporate feedback.
• Tabbycat produces a “shame list” of unsubmitted feedback, which you can optionally publish on the public-facing site to try to incentivise submission.

(How participants access adjudicator feedback submission is discussed in User identification above.)

Other considerations

Offline availability. If you like, you can also install Tabbycat on your own computer, rather than host it as website on a server. This means that you can use it offline. However installing Tabbycat in this manner will require the (at least brief) use of a command line interface.

Cost. Tabbie2 is free to use. Tabbycat is free to use for not-for-profit, not-for-fundraising tournaments; tournaments for profit or fundraising must make a donation of A$1 per team. In addition, larger tournaments that run on Tabbycat’s recommended web host (Heroku) may need to purchase an upgraded database service (the free tier has storage limits) which will cost around ~US$3 to use for the duration of a week-long tournament.

Documentation. Tabbycat has relatively extensive documentation that can be useful for learning how to use a particular feature or understanding what is happening at a technical level.

Hosting location. Tabbycat recommends using Heroku, an established cloud platform service for deploying web applications. Heroku is in turn hosted on Amazon Web Services (AWS). Both Heroku and AWS are highly reliable and widely used; downtime for both has historically been (at worst) less than 0.05% over an annual period.

Tabbie2 is hosted on Uberspace; a pay-what-you-want web hosting service. To the best of our knowledge, uptime statistics are not available.

Multi-format support. If you are interested in tabbing both four- and two- team formats there may be some value in using and learning Tabbycat as it will let you use the same software in both settings.

Comparison with Tournaman

Native app vs web app

The crucial strength — and limitation — of Tournaman is that it is a Windows desktop application. Naturally, being a desktop app limits the features it can offer, relative to web apps like Tabbycat or Tabbie2, since it can’t offer any online access. On the other hand, working with a desktop app can often be simpler than a web app.

Installation. You’ll need to run (or emulate) a Windows machine to run Tournaman. Assuming you’re using Windows, Tournaman’s installation process is easy and familiar.

Tabbycat has a simple one-click installation process if you’re deploying online (to Heroku). However, if you want to run Tabbycat on your own computer rather than a website, this is substantially more complicated. Local installations of Tabbycat work by having your computer emulate a web server, and while we’ve tried to make this as accessible as possible, a technical background is definitely helpful for this. Using our Docker-based method should be simple, but it’s not 100% reliable, and if it fails it can be difficult to figure out why. If internet access is available, we recommend running Tabbycat on Heroku.

Online features. Because Tournaman runs fully offline, it naturally can’t support many internet-based features: electronic ballots, online publication of draws and live team standings, and integrated tab release. Typically, if you wanted to publish anything online from Tournaman, you’d do so by publishing the files that Tournaman generates locally. In Tabbycat, all of these are built in, so there’s a single website for all tab information.

Multi-user access. Tournaman can be configured to allow networked ballot entry, but in order to set it up, you need to be comfortable with basic computer networking. This works best on small isolated networks that you control directly, e.g. a dedicated router set up in the tab room. It’s not a great idea to set this up on computers connected to a university-wide network: many IT departments won’t permit it, and even if they do, it’s insecure, since anyone on the network can access it.

Tournaman’s multi-user access is designed primarily to allow tab assistants to enter data. Key administrative tasks, such as draw generation and adjudicator allocation, must still be done on the computer on which Tournaman is installed. In contrast, web-based systems like Tabbycat and Tabbie2 allow users to login from any internet-connected device to access the functionality permitted by their account. This is often extremely useful if, say, you want to log in to a lectern computer, or have tab assistants work on mobile devices that they have with them.

If you choose to install Tabbycat offline (rather than on Heroku), it’s also possible to have the computer on which the local installation resides serve the website to other computers on the same network. This then permits anyone on the same network to access the “local” installation as if it were hosted on the internet. However, like Tournaman, such a configuration requires at least basic networking experience, and for security reasons is only advisable on small isolated networks that you control.

Backups and portability. Both Tournaman and Tabbycat (unlike Tabbie2) store data in a way that is completely accessible to you. Tournaman does this by saving files on your computer’s hard drive, while Tabbycat stores data in a SQL database that belongs to you.

It should be emphasized that in both Tournaman and Tabbycat, actually needing to revert to a backup is extremely rare. Almost always, any glitch or error that breaks the tab can be resolved by editing data directly, without needing to “roll back” to a previous state. In Tournaman, this is done by editing the files that it writes to your hard drive (they’re just XML files). In Tabbycat, this is done through the “Edit Database” area.

Tournaman’s storage of data as XML files makes backups easy, although effort should be made to have backups stored on other computers or the cloud (e.g. on Dropbox) in case the tab computer breaks or is lost. Restoring data from those backups (or transferring the tab to a different computer) is typically a simple process of copying the files back to the original location.

As for Tabbycat, in online installations, backups can be taken easily using Heroku’s database backup capability. However, restoring backups requires you to have the Heroku command line interface installed. In offline installations, PostgreSQL’s “dump” and “restore” commands are recommended, and may require some perseverance to get going reliability, particularly if you don’t have prior SQL experience.

Generally there is no need for data portability when working with an online copy of Tabbycat — the website can be accessed anywhere. However if working with an offline/local copy, a tab can be transferred between machines by creating a backup of the database and restoring it to the other machine’s database (doing so requires technical knowledge).

Running your tournament

Adjudicator feedback. Tournaman lets you assign judges rankings, however it does not directly manage or assist the process of collecting judge feedback. As such tab directors generally need to run a parallel feedback system, and then manually copy over changes to an adjudicator’s ranking into Tournaman itself. In contrast, Tabbycat has integrated methods for collecting judge feedback that allow it to be more easily issued, collected, viewed, and automatically translated into modifications to an adjudicator’s rank.

Adjudicator allocation. Tournaman has a fixed judge ranking scale and (from what we understand) has a relatively fixed procedure for allocating panels according to their absolute ranks. We are unsure about the exact mechanics of how this works, but broad details are available here.

As with the discussion of allocation interfaces vis-à-vis Tabbie2, there are a number of features in the Tabbycat allocation interface that mean it is more easily used in a collaborative setting and can display additional information to inform draws.

Flexibility in draw rules. As we’ve said, all major tab systems are WUDC-compliant. But if you want to deviate from WUDC rules, Tournaman has a few more options. Whereas Tabbycat allows you to use intermediate brackets (rather than pull-ups), Tournaman allows you to sacrifice power-pairing integrity for position balance (though this generally isn’t necessary to achieve position balance), fold within brackets and avoid teams hitting their own institution. On the other hand, Tabbycat allows you to tune how position balance trades off between teams (which the WUDC constitution doesn’t precisely specify).

Shadow draws. Tournaman allows you to create ‘shadow panels’ of adjudicators that can be applied to a draft draw prior to the generation of the real draw. For very large tournaments this can be a valuable method of front-loading some of the allocation process and reducing time pressure. Tabbycat does not have an equivalent feature or method, although one is planned.

Other considerations

Stability and development. Tournaman has been in use for over a decade and is generally considered to be stable and reliable. However, new features are relatively rarely added, and its being a native app means that it doesn’t boast as many features as Tabbycat or Tabbie2.

Cost. Tournaman is free to use. Tabbycat is free to use for not-for-profit, not-for-fundraising tournaments; tournaments for profit or fundraising must make a donation of A$1 per team. In addition, larger tournaments that run on Tabbycat’s recommended web host (Heroku) may need to purchase an upgraded database service (the free tier has storage limits) which will cost around ~US$3 to use for the duration of a week-long tournament.

Availability of source code. Tournaman’s code is closed-source, meaning it is not publicly available. If you do not have any coding experience this is probably not relevant to you, but if you do, having access to the source of Tabbycat can help you understand how the program works and customise it as needed.

Comparison with hand tabbing

Hand tabbing is easy, until it isn’t. Traditionally, using a spreadsheet has been the go-to option for smallish tournaments because, hey, you’re pretty handy with Excel, right? Making draws in spreadsheets (or on paper) seems like a pretty approachable task; ultimately it’s all cells and formulae and numbers, unlike the more arcane underpinnings of actual tab software.

However, hand tabbing does require you to have a good working knowledge of how your format’s rules work and how your spreadsheet software of choice can be made to work them. That process might be easy for you, or it might not be. But, either way, we’d like to think that Tabbycat offers a better alternative to hand-tabbing; regardless of how well you can actually hand-tab. The setup costs of creating a copy of Tabbycat are pretty low and you can speed through the process of draw creation, adjudicator allocation, and result entry at a pace. It’s still not going to be as fast a spreadsheet for a small tournament, but we think it’s getting pretty close. And in exchange for a little speed you get a much stronger guarantee of your draws being correct, options for online data entry, a more comprehensive and shareable final tab, and much more. Give it a shot!

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 & Acknowledgements 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. Note that because the feedback score is averaged across all pieces of feedback (rather than on a per-round total) rounds in which a person receives feedback from many sources (say from all teams and all panellists) could impact their average score much more than a round in which they only receive feedback from one or two sources.

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

Tabbycat doesn’t provide an in-built backup system; instead you should create copies of your database directly. Heroku provides a very good backup utility for all sites hosted on Heroku which makes this easy, 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.

If you’re using an online version of Tabbycat, it’s a good idea to download the backups. While it’s extremely rare to lose internet access or have an outage in a critical web service (i.e., Heroku), having a local copy of your backups allows you to restore your tab to a local installation if this ever happens.

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:

1. Go to the Heroku Dashboard and click on your app.
2. Under Installed add-ons, go to Heroku Postgres.
3. Scroll down, and click on the Capture Backup button.
4. Once the capture has finished, a Download button will be available.

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 download the most recently captured backup:

$ heroku pg:backups:download

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.

Restoring a Heroku backup to a local installation

As detailed in the Heroku Dev Center, you can restore a downloaded Heroku backup to a local installation. This might be useful if, say, your internet connection breaks irrecoverably in the middle of a tournament and you need to run offline. Of course, for this to work, you need to have downloaded your backup before your internet connection broke—a good reason to download a copy of your backups as soon as you make them.

Assuming your download is called latest.dump (this is the default name), your PostgreSQL username is tabbycat, and you wish to call your local database fromheroku (if not, replace arguments as appropriate):

$ createdb fromheroku -h localhost -U tabbycat
$ pg_restore --no-acl --no-owner -h localhost -U tabbycat -d fromheroku latest.dump

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)	Descrption
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: They are in the top n teams overall, and in the top three teams from their institution. They have at least as many wins as the nth-ranked team, and they are the top team from their institution. 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:

1. Create (and name) a break category
2. Create break rounds for the category
3. 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.

Summary of options

Options are set in the Configuration page as described in starting a tournament.

Option	Description	Allowable values
Draw odd brackets	How to resolve odd brackets	Pull up from top Pull up from bottom Pull up at random If sides are Random or Balance: Intermediate Intermediate with bubble-up-bubble-down If sides are Pre-allocated: Intermediate 1 Intermediate 2
Draw side allocations	How to allocate aff/neg	Random Balance Pre-allocated Manual ballot
Draw pairing method	How to pair teams within brackets	Slide Fold Adjacent Random
Draw avoid conflicts	How to avoid history/institution conflicts	Off One-up-one-down

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.

The big picture

When generating a power-paired draw, Tabbycat goes through five steps:

1. First, it divides teams into “raw brackets”, grouping them by the number of wins.
2. Second, it resolves odd brackets, applying the odd brackets rule to make sure there is an even number of teams in each bracket. This is often called “pulling up” teams.
3. Third, within each bracket, it pairs teams into debates using the pairing method.
4. Fourth, if enabled, it adjusts pairings to avoid history or institution conflicts.
5. Finally, it assigns sides to teams in each debate.

For each of these steps except the first, Tabbycat allows you to choose between a number of different methods.

Explanations of options

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 (the “intermediate bubble”). It then takes teams from the next bracket down and moves them up 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 can choose to 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, take teams from the bracket after that, and so on, until the (original) odd bracket is filled. Higher brackets are always filled first. You can choose to 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. Then, take 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:
  1. Click Admin on the bottom right of any page after logging into an account with superuser access.
  2. Next to Teams, click Change.
  3. Click on the name of the team you want to edit side allocations for.
  4. 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 draw/management/commands/generatesideallocations.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.
• Adjacent: 1 vs 2, 3 vs 4, 5 vs 6, 7 vs 8, 9 vs 10. (Also known as high-high pairing.)
• Random: paired at random within bracket.

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.

One-up-one-down 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.

Note

Teams imported without an institutional affiliation are (for conflict avoidance purposes) considered to all be from the same institution and will trigger conflicts as described above. If this is a concern it can be assigning ‘fake’ institutions (i.e. Swing 1) to each unaffiliated team.

What do I do if the draw looks wrong?

You can edit match-ups directly from the draw page. Functionally, 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.

Draw Generation (BP)

The draw generator for British Parliamentary tournaments tries to rotate teams through positions by assigning them positions they’ve been in less often before the current round.

Summary of options

Options are set in the Configuration page as described in starting a tournament. Options in italics with an asterisk are not WUDC-compliant. The recommended options are shown in bold.

Option	Description	Allowable values
Pullup distribution	Where pullup teams get placed	Anywhere in bracket All in the same room*
Position cost	Which cost function to use to indicate which position profiles are preferred	Simple Rényi entropy Population variance
Rényi order	Order of Rényi entropy	Any non-negative number (default: 1, i.e. Shannon entropy)
Position cost exponent	Degree to which large position imbalances should be prioritised	Any non-negative number (default: 4)
Assignment method	Algorithm used to assign positions	Hungarian* Hungarian with preshuffling

The big picture

To try to achieve position balance, Tabbycat treats the allocation of teams to debates as an assignment problem. That is, it computes the “cost” of assigning each team to each position in each debate, and finds an assignment of all teams to a position in a debate that minimises the total cost (the sum over all teams).

A simple example

Here’s a small example, to illustrate the idea. Say you have a tournament with 16 teams, and you’re about to draw round 4. There are sixteen “places” in the draw: four positions in each of four rooms. Tabbycat calculates the “cost” of putting each team in each place, and puts them in a matrix, like this:

Room	Top				Second				Third				Bottom
Position	OG	OO	CG	CO	OG	OO	CG	CO	OG	OO	CG	CO	OG	OO	CG	CO
A (8)	16	16	16	0	∞	∞	∞	∞	∞	∞	∞	∞	∞	∞	∞	∞
B (7)	16	0	16	16	∞	∞	∞	∞	∞	∞	∞	∞	∞	∞	∞	∞
C (7)	16	16	0	16	∞	∞	∞	∞	∞	∞	∞	∞	∞	∞	∞	∞
D (6)	16	0	16	16	16	0	16	16	∞	∞	∞	∞	∞	∞	∞	∞
E (6)	0	16	16	16	0	16	16	16	∞	∞	∞	∞	∞	∞	∞	∞
F (6)	16	16	0	16	16	16	0	16	∞	∞	∞	∞	∞	∞	∞	∞
G (5)	∞	∞	∞	∞	16	0	16	16	∞	∞	∞	∞	∞	∞	∞	∞
H (5)	∞	∞	∞	∞	16	0	16	16	∞	∞	∞	∞	∞	∞	∞	∞
I (4)	∞	∞	∞	∞	∞	∞	∞	∞	16	16	0	16	∞	∞	∞	∞
J (4)	∞	∞	∞	∞	∞	∞	∞	∞	16	16	16	0	∞	∞	∞	∞
K (3)	∞	∞	∞	∞	∞	∞	∞	∞	0	16	16	16	0	16	16	16
L (3)	∞	∞	∞	∞	∞	∞	∞	∞	16	16	0	16	16	16	0	16
M (3)	∞	∞	∞	∞	∞	∞	∞	∞	16	16	16	0	16	16	16	0
N (3)	∞	∞	∞	∞	∞	∞	∞	∞	0	16	16	16	0	16	16	16
O (1)	∞	∞	∞	∞	∞	∞	∞	∞	∞	∞	∞	∞	16	16	16	0
P (1)	∞	∞	∞	∞	∞	∞	∞	∞	∞	∞	∞	∞	0	16	16	16

Each “16” is the cost of putting a team in a position it’s seen once; each “0” is the cost of putting a team in the position it hasn’t. (Details of how this is calculated are below.) For example, team A (on 8 points) has been in every position except CO. The ∞’s indicate places where the team isn’t allowed to go, because the room isn’t in their bracket. For example, the three teams on 6 points (D, E, F) can go in either the top or second room, because any of them can be the pullup team.

The algorithm then chooses entries so that one is selected from each row and one is selected from each column, in a way that minimises the sum of the selected entries. In this case, the selected entries are highlighted in blue. For example, the top room comprises teams E (OG), B (OO), C (CG) and A (CO).

Sometimes, particularly in round 4, it simply isn’t possible to “satisfy” everyone. For example, among the top eight teams, five haven’t been in OO, but only two can be accommodated within those brackets. In this case, teams B and G got lucky; there are also many other draws that would have incurred the same total cost.

More generally, in most cases, there will be many optimal solutions. To randomise the selection among them, Tabbycat (under default settings) randomly permutes the rows and columns of the matrix before starting the assignment algorithm.

Explanations of options

Pullup distribution

If the number of teams in a bracket is not a multiple of four, it pulls up teams from the next bracket down. The pullup distribution then governs how those teams are paired into the upper bracket.

The available options are as follows:

• Anywhere in bracket: The pullup teams are treated as if they were any other team in their new bracket. For example, if there are 17 teams in a 10-point bracket, then the three 9-point teams that get pulled up may be paired anywhere in the 10-point bracket, independently of each other. Chance might put them in the same room, but more likely, they will not all be in the same room, so there will be multiple pullup rooms in the 10-point bracket.
• All in the same room: All of the pullup teams will be paired into the same room. This means that there will be at most one pullup room per bracket, effectively creating an “intermediate bracket”.

Note

While it can be argued that the All in the same room setting is fairer, it is prohibited by the WUDC constitution. If your tournament follows WUDC rules, you cannot use this setting.

The teams that get pulled up aren’t specifically chosen—they’re just assigned as part of the algorithm described above, which optimises for position balance. Tabbycat doesn’t support taking anything else into account when choosing pullup teams. (WUDC rules wouldn’t allow it, either.)

Position cost options

The position cost function is a function that indicates how “bad” it would be if a team were to be allocated a certain position (OG, OO, CG, CO) in a debate. When generating a draw, Tabbycat chooses from among the draws that minimise the sum of the position costs for each team.

More formally:

• A position history or just history is a 4-tuple where each element is the number of times a team has already been in the corresponding position. For example, means that a team has been in OO twice, CG and CO once each, and hasn’t been in OG.
• A cost function is a function specifying how “bad” it would be if a team with position history were assigned the position in the next round.

Tabbycat allows you to choose from a number of different position cost functions, as well as a position cost exponent . Then, when allocating teams to debates, Tabbycat allocates teams to positions to minimise

where is the set of all teams, is the position history of team and is the position to which team would be allocated.

Position cost exponent

The position cost exponent controls how different teams trade off with each other.

• The larger is, the more concerned it is with preventing very bad situations. That is, it will give more teams some slight unevenness in order to prevent one team from getting a very uneven history.
• The smaller is, the more concerned it is with preventing any unevenness. That is, it will try to keep more teams from being uneven at all, at the cost of possibly letting just one team get a very uneven history.
• At the large extreme, as , it will do everything it can to minimise the plight of the worst-off team, and it won’t care for any team other than the worst-off.
• At the small extreme, as , it will do everything it can to minimise the number of teams with a non-optimal profile—but if it’s impossible to protect a team from sub-optimality, it won’t care how uneven the unlucky team gets.

The “balanced” approach would be , which just takes the cost function as-is. This doesn’t mean that this is the best idea, however—you’d typically want to bias towards preventing very uneven histories a bit more. Most tournaments will probably want to be somewhere between 2 and 5. (Note that need not be an integer.)

Position cost functions

Tabbycat allows you to choose between three position cost functions : Simple, Rényi entropy and Population variance.

In the descriptions that follow, , the set of all BP positions.

Simple

The simple cost function returns the number of times the team has already been in position , less the number of times the team has been in its least frequent position. That is,

where is the element of corresponding to position .

Rényi entropy

Informally speaking, the Rényi entropy is a measure of the diversity of the positions in a team’s history. A history consisting only of one position has low entropy, while a history that is perfectly evenly distributed has high entropy. The Rényi entropy cost function reverses this intuition, so that an even hypothetical history has low cost, while an uneven hypothetical history has high cost.

The Rényi entropy takes one parameter, known as its order, , which will be further discussed below.

More formally, the Rényi entropy cost function is defined as

where

• is the number of rounds the team has competed in so far.

• is the normalised hypothetical position history that would arise if a team with history were to be allocated position in the next round; that is,

  

  Note that is a probability distribution (that is, its elements sum to 1).

• is the Rényi entropy of order of a probability distribution, defined as

  

  In the special (limiting) case where , it reduces to the Shannon entropy,

  

  Note that for all , (since there are four positions in BP).

The Rényi order is the parameter above, and it controls what it means to be “even among positions” for a team. Note that “evenness” is not easily defined. After round 8, which position history is more even: (0, 2, 3, 3) or (1, 1, 1, 5)? The Rényi order allows us to tune this definition.

• The smaller is, the more it cares that teams compete in every position at least once, favouring (1, 1, 1, 5) over (0, 2, 3, 3): it’s worse to have never OGed, than it is to have COed five times.
• The larger is, the more it cares that teams do not compete in any (one) position too many times, favouring (0, 2, 3, 3) over (1, 1, 1, 5): it’s worse to have COed five times, than it is to have never OGed.
• At the small extreme, as , it only counts how many positions a team has seen at least once, and doesn’t care about the distribution among them so long as a team has been in each position once.
• At the large extreme, as , it only looks at how many times each team has seen its most frequent position, and tries to keep this number even among all teams.

The “balanced” approach would be (the Shannon entropy), though of course it’s arguable what “balanced” means. Tabbycat defaults to this value.

To give some intuition for the useful range: In round 9, a strict ordering by number of positions seen at least once occurs for approximately . A strict ordering by number of times in the most frequent position occurs for . Changing outside the range will still affect the relative (cardinal) weighting between teams, but will not affect the ordinal ranking of possible histories.

The purpose of weighting costs by is to prioritise those teams who have competed in every round over those who have competed in fewer rounds.

Population variance

The population variance cost function is just the population variance of the history 4-tuple,

where is the hypothetical position history that would arise if a team with history were to be allocated position in the next round; that is,

and where is the mean of ,

At the extremes, a team that has seen all positions evenly will have a population variance of zero, while a team that has seen just one position times will have a population variance of .

Assignment method

Tabbycat uses the Hungarian algorithm to solve the assignment problem of assigning teams to positions in debates. This can be run with or without preshuffling:

• Hungarian algorithm just runs the Hungarian algorithm as-is, with no randomness. This probably isn’t what you want.

• Hungarian algorithm with preshuffling also runs the Hungarian algorithm on the position cost matrix, but shuffles the input so that the draw is randomised, subject to having optimal position allocations.

  Preshuffling doesn’t compromise the optimality of position allocations: It simply shuffles the order in which teams and debates appear in the input to the algorithm, by randomly permuting the rows and columns of the position cost matrix. The Hungarian algorithm still guarantees an optimal position assignment, according to the chosen position cost function.

Note

Running the Hungarian algorithm without preshuffling has the side effect of grouping teams with similar speaker scores in to the same room, and is therefore prohibited by WUDC rules. Its inclusion as an option is mainly academic; most tournaments will not want to use it in practice.

No other assignment methods are currently supported. For example, Tabbycat can’t run fold (high-low) or adjacent (high-high) pairing within brackets.

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.

Standings Rules

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. For two-team formats, this is just a synonym for wins, and differs only in column labelling. For BP, this is 3 points for a first, 2 for a second, 1 for a third and 0 for a fourth.
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.

Motions Standings Test

The motions tab and motions standings page applies a statistical test to estimate the degree to which a motion is imbalanced. This is calculated by first making an underlying assumption that a motion is generally fair. This will be our null hypothesis: that, for a given motion, affirmative teams won the same number of times as negative teams.

Our chi-squared test will then be centred around disproving this hypothesis. If we disprove the hypothesis, we say that, in the context of this tournament and this draw, the motion ended up being unbalanced. However (technically speaking) if we fail to reject the null hypothesis, we would conclude that there is insufficient evidence to suggest that the motion was unbalanced in the context of this tournament.

The test proceeds by calculating the chi-squared stat, then running a series of tests. The tests are where we go a little off-book with respect to statistical methodology. Normally we would test at a single “level of significance” (ie. with a certain degree of certainty), but that’s insufficient in telling us how bad a motion ended up being. So, instead, we conduct a range of tests with a range of levels of significance, and calculate the minimum level of significance that causes our null hypothesis to be rejected. Using the minimum level of significance that rejects our null hypothesis, we can then grade the fairness of the motion on a scale. Motions whose tests fall below a certain threshold will be considered fair, while others will be graded based on the minimum.

For formats with topic selection, the same test is applied using the number of affirmative and negative vetoes in place of wins. The assumption here is that, during the time allotted for motion selection, teams estimate how appealing a motion is from their position, and then veto the topic that they feel is least favourable. Thus, the null hypothesis is that a motion that is perceived of as fair would be vetoed by affirmative and negative teams to an equal degree.

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 & Acknowledgements 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

1. Choose a name. We name importers after items of clothing in alphabetical order (starting at ‘Anorak’).
2. Write a subclass of BaseTournamentDataImporter.
3. 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:

1. 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.
2. On each line:

1. It passes the dict given by the DictReader to interpreter. The interpreter modifies the dict (or creates a new one) to prepare it for the model constructor, and returns it.
2. The dict returned by interpreter is then passed as keyword arguments to the model 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 a Person.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 by self.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:

1. Go to BASE_URL/admin/auth/user/ and click “Add user” in the top right.
2. 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.
3. 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 & Acknowledgements

Authors

Tabbycat was authored by Qi-Shan Lim for Auckland Australs 2010. The current active developers are:

• Philip Belesky (pb-e-mail)
• Chuan-Zheng Lee (cz-e-mail)

Please don’t hesitate to contact us with any suggestions, expressions of interest or generally anything relating to Tabbycat.

Contributors

• Thevesh Theva contributed the algorithm for calculating the liveness of teams within a particular break category.
• Viran Weerasekera contributed the statistical tests used to estimate the degree to which a motion’s results and vetoes are balanced.
• Viran Weerasekera, Valerie Tierney, Molly Dale, Madeline Schultz, and Vail Bromberger contributed to the “Tournament Logistics” section of our documentation.

Sponsors

• Thanks to the Western Australian Debating League for sponsoring various features related to organising division-based tournaments and round-robin based draw methods.

Change Log

2.0.7

Release date: 13 April 2018

• Fixed an issue preventing draws with pre-allocate sides generating

2.0.6

Release date: 20 March 2018

• Added reminder to add own-institution conflicts in the Edit Database area
• Other minor fixes

2.0.5

Release date: 7 February 2018

• Improved the printing of scoresheets and feedback forms on Chrome.
• Other minor fixes

2.0.4

Release date: 22 January 2018

• Add alert for users who try to do voting ballots on BP-configured tournaments
• Fixed issue where draws of the “manual” type would not generate correctly
• Fixed issue where a ballot’s speaker names dropdown would contain both team’s speakers when using formats with side selection
• Fixed issue where scoresheets would not show correctly under some configurations
• Improved display of really long motions when using the inbuilt motion-showing page
• Other minor fixes

2.0.3

Release date: 3 December 2017

• Fixed issue where the ‘prefix team name with institution name’ checkbox would not be correctly saved when using the Simple Importer
• Removed the scroll speed / text size buttons on mobile draw views that were making it difficult to view the table
• Improved the display of the motions tab page on mobile devices and fixed an issue where it appeared as if only half the vetoes were made

2.0.2

Release date: 27 November 2017

• Fixes and improvements to diversity overview

  • Fixed average feedback rating from teams, it was previously (incorrectly) showing the average feedback rating from all adjudicators
  • Gender splits for average feedback rating now go by target adjudicator; this was previously source adjudicator
  • Persons with unknown gender are now shown in counts (but not score/rating averages); a bug had previously caused them to be incorrectly counted as zero
  • Improved query efficiency of the page

• Improved the BP motions tab for out-rounds by specifying advancing teams as “top/bottom ½” rather than as 1st/4th and removed the average-points-per-position graphs that were misleading
• Improved handling of long motions in the motion display interface
• Fixed issue where creating BP tournaments using the wizard would create an extra break round given the size of the break specified
• Fixed auto-allocation in consensus panels where there are fewer judges than debates in the round
• Fixed reply speaker validity check when speeches are marked as duplicate
• Prohibit assignment of teams to break categories of other tournaments in Edit Database area

2.0.1

Release date: 21 November 2017

• Fixed issue where results submission would crash if sides are unconfirmed
• Fixed issue where scoresheets would not display properly for adjudicators who lack institutions
• Fixed issue where the round history indicators in the Edit Adjudicators page would sometimes omit the “rounds ago” indicator

2.0.0 (Iberian Lynx)

Release date: 13 November 2017

• British Parliamentary support

  • Full support for British Parliamentary format has been added and we’re incredibly excited to see Tabbycat’s unique features and design (finally) available as an option for those tabbing in the predominant global format
  • As part of the implementation of this format we’ve made significant improvements over existing tab software on how sides are allocated within BP draws. This means that teams are less likely to have ‘imbalanced’ proportions of side allocations (for example having many more debates as Opening Government than Closing Opposition)
  • We’ve added a new “Comparisons” page added to the documentation to outline some of the key differences between Tabbycat and other software in the context of BP tabbing

• Refreshed interface design

  • The basic graphic elements of Tabbycat have had a their typography, icons, colours, forms, and more redesign for a more distinctive and clear look. We also now have an official logo!
  • The “Motions” stage of the per-round workflow has now been rolled into the Display area to better accommodate BP formats and consolidate the Draw/Motion ‘release’ process
  • Sidebar menu items now display all sub-items within a section, such as for Feedback, Standings, and Breaks
  • Better tablet and mobile interfaces; including a fully responsive sidebar for the admin area that maximises the content area
  • More explicit and obvious calls-to-action for the key tasks necessary to running a round, with better interface alerts and text to help users understand when and why to perform crucial actions
  • Redesigned motions tab page that gives a better idea of the sample size and distribution of results in both two- and three- team formats

• Improved handling of Break Rounds ballots and sides allocation

  • The positions of teams within a break round are now created by the initial draw generation in an ‘unset’ state in recognition that most tournaments assign these manually (through say a coin toss). This should help clarify when showing break rounds draws when sides are or are not finalised
  • Break rounds ballots for formats where scores are not typically entered (i.e. BP) will only specify that you nominate the teams advancing rather than enter in all of the speakers’ scores

• Now, like Break Categories, you can define arbitrary Categories such as ‘Novice’ or ‘ESL’ to create custom Speaker tabs for groups of Speakers
• You can now release an Adjudicators Tab showing test scores, final scores, and/or per-round feedback averages
• Information Slides can now be added to the system; either for showing to an auditorium within Tabbycat or for displaying alongside the public list of motions and/or the motions tab
• Teams and adjudicators are no longer required to have institutions; something that should be very useful when setting up small IVs and the like
• Private URLs can now be incrementally generated. Records of sent mail are now also kept by Tabbycat, so that emails can be incrementally sent to participants as registration data changes

• Quality of life improvements

  • After creating a new tournament you will now be prompted to apply a basic rules and public information preset
  • Better handling of errors that arise when a debate team is missing or where two teams have been assigned the same side
  • Fixed issue where the adjudicator feedback graphs would not sort along with their table
  • The Feedback Overview page now makes it more clear how the score is determined, the current distribution of scores, and how scores affect the distribution of chairs, panellists, and trainees
  • Speaker tabs now default to sorting by average, except for formats where we are certain that they must be sorted by total. The speaker tab page itself now prominently notes which setting is is currently using
  • ‘Feedback paths’ now default to a more permissive setting (rather than only allowing Chairs to submit feedback) and the Feedback Overview page will note that current configuration
  • Emails can be assigned to adjudicators and teams in the Simple Importer
  • More of the tables that allow you to set or edit data (such as the check-in tables for adjudicators, teams and venues) now automatically save changes
  • When adding/editing users extraneous fields have been hidden and the “Staff” and “Superuser” roles have new sub-text clarifying what they mean for users with those permissions
  • Team record pages now show cumulative team points, and if the speaker tab is fully released, speaker scores for that team in each debate

1.4.6

Release date: 23 October 2017

• Fixed issue where speaker standings with a large amount of non-ranking speakers would cause the page to load slowly or time-out.

1.4.5

Release date: 14 October 2017

• Added warning message when adjudicator scores are outside the expected range
• Fixed handling of uniqueness failure in simple importer for teams

1.4.4

Release date: 27 September 2017

• Fixed Vue dependency issue preventing Heroku installs after a dependency release
• Fixed issue with formatting non-numeric standings metrics
• Fixed behaviour of public tabs when all rounds are silent

1.4.3

Release date: 9 September 2017

• A number of improvements to error handling and logging
• Changed the “previous round” of an elimination round to point to the last one in the same break category
• Other minor bug fixes

1.4.2

Release date: 23 August 2017

• Minor bug fixes and error logging improvements

1.4.1

Release date: 2 August 2017

• Fixed bug that prevented edited matchups from being saved
• Added flag to prevent retired sites from using the database for sessions

1.4.0 (Havana Brown)

Release date: 26 July 2017

• Overhauled the adjudicator allocation, venue allocation, and matchups editing pages, including:

  • Upgraded to Vue 2.0 and refactored the code so that each page better shares methods for displaying the draw, showing additional information, and dragging/dropping
  • When dragging/dropping, the changed elements now ‘lock’ in place to indicate that their saving is in-progress
  • Added conflicts and recent histories to the slideovers shown for teams/adjudicators
  • Added ‘ranking’ toggles to visibly highlight adjudicator strengths and more easily identify unbalanced panels
  • Each interface’s table is now sortable by a debate’s importance, bracket, liveness, etc.

• Added a new “Tournament Logistics” guide to the documentation that outlines some general best practices for tabbing tournaments. Thanks to Viran Weerasekera, Valerie Tierney, Molly Dale, Madeline Schultz, and Vail Bromberger for contributing to this document
• Added (basic) support for the Canadian Parliamentary format by allowing for consensus ballots and providing a preset. However note that only some of the common draw rules are supported (check our documentation for more information)
• Added an ESL/EFL tab release option and status field
• Added a chi-squared test to measure motion balance in the motion standings/balance. Thanks to Viran Weerasekera for contributing this
• The Auto Allocate function for adjudicators will now also allocate trainees to solo-chaired debates
• Added a ‘Tab Release’ preset for easily releasing all standings/results pages after a tournament is finished
• Added ‘Average Speaks by Round’ to the standings overview page
• Fixed issue where the Auto Allocator was forming panels of incorrect strengths in debates identified as less important
• Fixed issue where toggling iron-person speeches on and off wouldn’t hide/unset the relevant checkboxes
• Fixed issue where VenueCategories could not be edited if they did not have Venues set
• Various other small fixes and improvements

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.5

Release date: 12 January 2017

• A number of minor bug fixes and improvements to documentation

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 accommodate 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. While at its core Tabbycat is a software project, you do not need to know how to code or use Git in order to help. We welcome feedback and ideas based on your tabbing experience and appreciate suggestions or proposals for how to improve the wording, translation, and design of our interface and documentation.

Feel free to join our Facebook group if you have any questions about how to get started.

Feedback and ideas

These can be added as issues in the GitHub repository; posts in our Facebook group; or as an email to the developers.

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 macOS, etc.)
• Any details about your tournament and setup that might be helpful in troubleshooting
• Detailed steps for how to reproduce the bug

Getting started with development

• 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

  • A number of our tests use Selenium and ChromeDriver to simulate in-browser functionality. They will fail if you do not have the Chrome browser installed.

• By default the development server’s build process will broadcast livereload events; installing one of their browser plugins can make testing front-end changes easier.

• A number of extra dependencies are required for running tests, linting, and serving the documentation. These can be installed with:

  $ pip install -r 'requirements_development.txt'
  

Style guide

For python code, 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 .

For stylesheets, we use stylelint to enforce the AirBnB CSS styleguide. The relevant code can be checked by using:

$ npm run stylelint

For javascript, we use eslint to enforce the AirBnB javascript styleguide. The relevant code can be checked by using:

$ npm run eslint

For the front end interface design there is a style guide available at “/style/” once a tournament has been setup.

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 cat breeds as the code names for major versions.

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 development dependencies and 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.

Project Structure

• bin contains a number of convenience scripts for starting/stopping Docker, and the webserver/asset pipeline.
• data contains the sample data sets and fixtures used to setup demo tournaments and in automated tests respectively
• docs contains our document source files and images (although some are linked from the root directory)

• tabbycat is the main directory containing the Django project

  • locale contains translation strings for shared templates (others are in respective app directories)
  • templates contains shared html templates, stylesheets, javascript source files, and Vue.js components/mixins.
  • utils contains shared utilities
  • All other folders are the Django apps that contain specific views, models, and templates for functions such as draw generation/display, or recording results. Each has sub-folders for tests and templates.

• In the root directory there are a number of files defining our python and javascript dependencies, core configuration files, and key documents like the README

Release Checklist

1. Check that all migrations have been generated and committed into Git
2. Bump version number in docs/conf.py
3. Bump version number and (if applicable) codename in tabbycat/settings.py
4. Update the main CHANGELOG.rst file (including release date)

5. Check the major current deployment options, including:

   1. The deploy_heroku.py script
   2. The Tabbykitten version
   3. Docker (macOS, Windows 10*) and Docker Toolbox (Windows 10 Home) methods
   4. Using Bash and Powershell on Windows
   5. Using Terminal on macOS (at least test out a fresh install of the npm/pip dependencies)

6. Check that the last Travis CI build passed and run the full local test suite (this will include the Selenium tests that are not on Travis)
7. Shift remaining issues from the Github Milestone
8. Create and finish the release branch as per git-flow
9. Ensure the tag is correct (vX.Y.Z) and published to GitHub
10. Back-merge master to the kitten branch
11. Back-merge develop to the in-progress feature branches
12. Push master to the release pipeline repository
13. Issue a formal release with change notes on GitHub
14. Post change notes on the Facebook page/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 partial list of major national and international tournaments (that we know of) which have used Tabbycat.

2017

• APU Philosophy CHallenge
• ANU Spring IV
• Wollongong Easters
• Australasian Wom*ns Debating Championships
• Asia World Schools Debating Championship
• Asia British Parliamentary Championships
• Cambridge Asian Schools BP Championships
• Cambodia United Asian Debating Championship
• Kings College London IV
• KPU Pro Ams
• New Zealand Easters
• Swords Mini-Gong
• UCD Law Society IV
• UCD Vice President’s Cup
• UQ Australs
• UT MARA Open
• Victoria Cup IV
• Western Sydney BP Championship
• Yale IV

2016

• Sydney Easters
• Joynt Scroll 2016
• Malaysia Debate Open
• New Zealand Easters 2016
• Perth Australs
• Thailand United Asian Debating Championships
• The National Law School Debate
• The Khazak National Schools Debating Championship

2015

• Bali United Asian Debating Championships
• Daejeon Australs
• Joynt Scroll
• Malaysia Debate Open
• New Zealand Easters
• The National Law School Debate
• UNSW/UTS Easters

2014

• Joynt Scroll 2014
• NTU United Asian Debating Championships
• Otago Australs

2012

• Wellington Australs

2010

• Auckland Australs