Developing the app
======================================================

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

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
* libxml2-devel
* libxslt-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**

Using 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



Installing prereqs with pip
***************************

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

  pip install kitchen paver
  pip install -r requirements.txt

There are some odd dependencies in the requirements that distutils doesn't always
figure out so you may need to run the install command more than once.

Configuring initial dev environment
***********************************

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

  python initialize.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.

Although the configuration file has now been generated, the database still
requires initial initialization::

  python initialize.py init_db


Initial Internal Configuration
***********************************

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 initialize.py script::

  python initialize.py add_user -u 'admin' -p 'adminadminadmin'
  python initialize.py add_release -n 19
  python initialize.py add_milestone -n 19 -r alpha -b 834084 -a 834085

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


Running initial sync
********************

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

  DEV='true' python sync_db.py


Migrating data using alembic
****************************

To install `alembic <https://alembic.readthedocs.org/en/latest/index.html>`_, use (inside the virtualenv)::

  pip install alembic

To upgrade database to the most recent revision, use::

  alembic upgrade head

To downgrade database back to the beginning, use::

  alembic downgrade base

To upgrade database to a specific revision, use::

  alembic upgrade 42d71a06dd50

To create a revision, use::

  alembic revision -m "Create a table"

This will create a file called, e.g., 42d71a06dd50_create_a_table.py in alembic/versions. The file contains *upgrade* and *downgrade* methods that need to be adjusted to reflect desired migration.

To create an auto-generated revision, use::

  alembic revision --autogenerate -m "Create a table"


Building Project CSS
--------------------

The CSS used is compiled from `SASS <http://sass-lang.com/>`_ using
`Compass <http://compass-style.org/>`_. While the rendered CSS is in the git
tree, do not make changes to those files if you expect them to be persistent
because they are only there for convenience.

The `Zurb Foundation <http://foundation.zurb.com/>`_ front end framework is used
as a base for a grid, among other UI elements. It will also need to be installed
on the development system in order to compile the source SASS files.

Installing Tools
****************

The following packages are needed::

  sudo yum install rubygem-compass rubygem-sass

Once compass is installed, grab the Zurb Foundation gem::

  sudo gem install zurb-foundation


Building CSS
************

From the root of the git tree, run::

  compass compile

You can also have compass watch the scss files for changes and rebuild every
time a change is detected::

  compass watch