Developers

Prerequisites

Make sure you have the virtualenv tool available. You can find further instructions in the Installation section or at the virtualenv website.

All steps below assume you are using a virtual environment named env inside the root directory of the git checkout. It’s not important what name you use, this is only chosen to make the documentation consistent. Most of the commands below reference the pip, virtualenv, and python instances installed in the env environment. This ensures that they run in the context of the environment where we’ve set up the Avalon Music Server.

Environment Setup

First, fork the Avalon Music Server on GitHub.

Check out your fork of the source code.

$ git clone https://github.com/you/avalonms.git

Add the canonical Avalon Music Server repo as upstream. This might be useful if you have to keep your branch / repo up to date before creating a pull request.

$ git remote add upstream https://github.com/tshlabs/avalonms.git

Create and set up a branch for your awesome new feature or bug fix.

$ cd avalonms
$ git checkout -b feature-xyz
$ git push origin feature-xyz:feature-xyz
$ git branch -u origin/feature-xyz

Set up a virtual environment.

$ virtualenv env

Enter the virtualenv install required dependencies.

$ source env/bin/activate
$ pip install --allow-external argparse -r requirements.txt
$ pip install -r requirements-dev.txt
$ pip install -r requirements-prod.txt

Install the checkout in “development mode”.

$ pip install -e .

Running The Server

The Avalon Music Server WSGI application can be run with Gunicorn (which was installed above from the requirements-prod.txt file) or any other WSGI application server. Make sure that you have entered the virtualenv you created earlier.

$ gunicorn --preload avalon.app.wsgi:application

Memory Profiling

The Avalon Music Server WSGI application can optionally log the memory used by various internal data structures. This can be useful for minimizing the resource footprint of the server when adding new features.

When enabled, memory usage will be writen to the configured logger. This feature is only enabled when the Pympler package is installed and the configured log level is DEBUG.

To enable this do the following.

Install the profiler.

$ pip install pympler

Change the Avalon Music Server log level in your local settings.py file.

LOG_LEVEL = logging.DEBUG

Contributing

Next, code up your feature or bug fix and create a pull request. If you’re new to Git or GitHub, take a look at the GitHub help site.

Useful Commands

The Avalon Music Server uses tox to run tests in isolated virtualenvs. You can run the tests using the command below. Make sure that you have entered the virtualenv you created earlier.

$ tox test

You can also run the unit tests for a specific Python version.

$ TOXENV=py33 tox test

If you’re making changes to the documentation, the command below will build the documentation for you. To view it, open up doc/build/html/index.html in your web browser.

$ fab clean docs