Support/Developer Tips

Here are a few tips and tricks we've accumulated while working on the new platform. Hopefully these are helpful to new developers or other contributors who want to get Kitsune up and running to hack on it.

Migrations

We use schema migrations to maintain our database structure. This allows us to keep a version history of the database (at least since the beginning of Kitsune).

All our migrations are kept in the /migrations/ folder, and start with a number. When adding a new migration, it needs to be the next in the sequence. So, for example, if the highest-numbered migration is 12, the next should be named 13-some-description.sql.

We have tools to help generate a migration—they're not perfect, but they get you started.

sqlall

When you add a new app to the INSTALLED_APPS tuple, you can use the sqlall command to generate a migration.

./manage.py sqlall <app-name>

The resulting SQL will be pretty close to what you need. (You can drop the BEGIN; and COMMIT; statements, as schematic uses transactions automatically.)

sqldiff

If you are making changes to a model in an app that already exists, you can use the sqldiff command to get the difference:

./manage.py sqldiff <app-name>

The resulting SQL will contain a lot more than you really need: it ALTERs every column. You should drop any statement that doesn't actually change anything, to make it easier for reviewers.

pdb and debugging

pdb, the Python debugger, is a fantastic tool that lets open a shell at any point in the execution of a program with one line:

import pdb; pdb.set_trace()

There are a couple of tricks to using it with our test-suite.

Enabling iPython

pdb's built-in shell is... OK, but iPython is better. To enable iPython in the pdb shell, run this:

echo "alias i from IPython.Shell import IPShellEmbed as IPSh; IPSh(argv='')()" >> ~/.pdbrc

Then in pdb, just type i<enter> to drop into iPython in the same context.

pdb and nose

pdb and nose have a love/hate relationship by default: nose captures stdout and prevents you from getting to the pdb prompt. On the other hand, nose also has switches to automatically drop into pdb on error or failure.

./manage.py test  # Cannot get into pdb
./manage.py test -s  # Tells nose not to capture stdout, can get to pdb
./manage.py test --pdb  # Drop into pdb if there's an error (E result)
./manage.py test --pdb-fail  # Drop into pdb if there's a failure (F result)

pip

pip is a package manager for Python that is an improvement over easy_install. It works well with virtualenv, which we also use. (In fact, virtualenv installs pip for you.)

Download Cache

A download cache can make pip install go much faster. There are just two steps to start using a download cache:

mkdir ~/.pip-cache
export PIP_DOWNLOAD_CACHE=~/.pip-cache

You probably want to put the second line into your .bashrc (or .zshrc) file as well, so it's automatically exported when you open the terminal.