====================================
Setting up a Development Environment
====================================


Setting up a development environment for the blocker tracking app is pretty
easy but different from installing the app in a production environment

**talk about git-flow**

Required Fedora Packages
========================

The instructions here will use virtualenv so that there are no potential
conflicts with system libs. At a bare minimum, you will need:

* python-virtualenv

* libcurl-devel

If you plan on developing against a database other than sqlite, you will need
to have that installed and configured, similarly to the production install
documentation **NEED LINK TO PRODUCTION DOCS HERE**

Create a Virtualenv
===================

Create a new virtualenv in the base of the source tree::

  virtualenv --distribute env_blockerbugs


In order to install python packages into the virtualenv or use the packages
inside the virtualenv, it must be activated::

  source env_blockerbugs/bin/activate

Install dependencies into the Virtualenv
****************************************

To get all of the python packages into the virtualenv, use pip inside the
virtualenv (ie. activate the virtualenv first)::

  pip install kitchen paver babel
  pip install python-fedora
  pip install -r requirements.txt

python-fedora will throw some errors about permissions, but that is expected and
doesn't affect it's operation. However, it is important to install separately as
the errors will stop the installation of other deps in the requirements file.

Configuring dev environment
===========================

To generate an initial config for a sqlite database, use the following command::

  python run_cli.py generate_config -d 'sqlite:////path/to/code/blockerbugs_db.sqlite'

The configuration file will be generated in the conf/ directory. While you would
copy this config file to /etc/blockerbugs in a production system, for a development
installation, just leave it in the conf/ directory.

The config generated by run_cli.py is very basic and may require tweaking to get
the environment that you're looking for.

''LINK TO CONFIGURATION OPTIONS''

Initializing the Environment (Lazy Method)
------------------------------------------

The quick and easy way to initialize the environment with default settings for
a recent Fedora release is to run::

  ./init_db.sh

This shell script will initialize the configured database, set up a release and
several milestones. The script is kept up to date for current Fedora releases
so that you don't need to memorize the relevant blocker and Freeze Exception
tracker bugs.

Initializing the Environment (Detailed Method)
----------------------------------------------

Most configuration post-installation is done using the cli. However, when working
in a development environment, that cli isn't directly available and we need to
use the run_cli.py helper script which exposes the same commands.

Once the config file has been generated, the database needs to be initialized::

  python run_cli.py init_db

There are some internal variables in the db which are wise to set before attempting
to run a sync. These are easily set using the run_cli.py script::

  python run_cli.py add_release -n 19
  python run_cli.py add_milestone -n 19 -r alpha -b 834084 -a 834085

This will add a F19 release and an alpha phase using 834084 and 834085 as
blocker and FE tracking bugs, respectively.

Running Sync Against Bugzilla and Bodhi
=======================================

To do an initial sync, simply run the following command::

  DEV='true' python run_cli.py sync

Alternatively, it is possible to run sync for only updates or only bugs::

  DEV='true' python run_cli.py sync-bugs
  DEV='true' python run_cli.py sync-updates

Running Unit Tests
==================

Unit tests have been written using `pytest <http://pytest.org/>`_ and can be run
from the root project directory with::

  TEST='true' py.test testing/

The ``TEST='true'`` part is rather important as some of the tests will wipe the
database and fill it with less useful data. The ``TEST`` configuration forces
the use of an in-memory SQLite3 database.