====================================
Development Tasks
====================================

Git Branching Strategy
======================

We're using a slightly modified version of Vincent Driessen's `A highly successful
git branching model <http://nvie.com/posts/a-successful-git-branching-model/>`_
and the associated `git-flow tool <https://github.com/nvie/gitflow>`_ (packaged
in Fedora as ``gitflow``).

Released code is kept in ``master`` and yet-to-be-released code is in ``develop``.
Generally, new code is submitted as feature branches of the form
``feature/tXXX-$FEATURE`` where ``XXX`` is the feature's ticket number in trac
and ``$FEATURE`` is a short human-recognizable phrase to identify the branch
without needing to memorize ticket numbers.

Submitting Code
===============

Code can be submitted in one of two ways: through pushing to a feature branch or
submitting a patch to `our reviewboard instance <https://reviewboard-tflink.rhcloud.com/>`_
Either way, the process is similar:

  * Create a review request on reviewboard
    - Please fill out the relevant fields (description, testing done, bugs fixed etc.)
    - Make sure you select the 'blockerbugs' group for the review request - this
      will email the ``qa-devel`` list and notify other developers of the review

  * Once the review is complete, merge the code into the ``develop`` branch.
    - If you do not have write privileges, this will be done for you

Creating a Review Request with post-review
------------------------------------------

An easy method for creating a review request involves using the ``post-review``
tool which is written by the reviewboard developers (Fedora package ``RBTools``).

If you're submitting a review request for the feature branch ``$FEATURE``, you
would use the following command from the repository's root directory to start
a minimal review request **after** pushing your branch to origin::

  post-review --tracking-branch=origin/develop --branch origin/feature/$FEATURE

This doesn't fill out all of the required fields and you will need to login to
the reviewboard instance in order to finish the review submission process but this
is at least a start.

Updating a Review Request with post-review
------------------------------------------

We wouldn't have a need for code reviews if the code never changed after initial
review. Many times, an update is needed to code before the review process is
complete.

To update an existing review request ``$ID`` (the id number of the review request
in reviewboard), use the following command **after** pushing your code to origin::

  post-review -r $REVIEW --tracking-branch=origin/develop --branch origin/feature/$FEATURE

Release Process
===============

The release process is relatively simple. At release time,

  * merge ``origin/develop`` into ``origin/master``, resolving any merge
    conflicts or issues.

  * Make sure that the version strings in ``blockerbugs.spec`` and ``blockerbugs/__init__.py``
    match and are correct. ``blockerbugs.spec`` should have a useful statement
    in the changelog corresponding to the changes in this latest release

  * Create a git tag on master

  * Push the changes in master and the new tag to origin

  * Build an SRPM with the new release and submit a scratch build to Koji

  * Request that the new build be pulled into infra's repository and deploy on
    staging

  * After a reasonable amount of testing, deploy to production


Building a Blockerbugs RPM
==========================

Step-by-step process for building an rpm (el6, probably) for devel, stg, production

These instructions are deliberately abstracted for version and branch so that
they can be used for other things than just releases. The relevant variables are:

  * ``$VERSION`` - the version as set in both ``__init__.py`` and ``blockerbugs.spec``

  * ``$RELEASE`` - the release as set in  ``blockerbugs.spec``

  * ``$BRANCH`` - the git branch you're working with (master, develop, feature/t123-foobar etc.)

  * ``$BASEDIR`` - the base directory for your git checkout

Make sure that all the files you're working on are committed in your git repo and
create a tarball by running this command in ``$BASEDIR``::

  git archive --format=tar --prefix=blockerbugs-$VERSION/ $BRANCH | gzip -c > blockerbugs-$VERSION.tar.gz

Create an srpm using mock and copy the result into ``$BASEDIR``::

  mock -r epel-6-x86_64 --buildsrpm --spec blockerbugs.spec --sources $BASEDIR
  cp /var/lib/mock/epel-6-x86_64/results/blockerbugs*.src.rpm $BASEDIR/.

From here, you can either build the rpm locally using mock or using a koji scratch
build.

Building Locally with Mock
--------------------------

Run this command to build an rpm locally with mock (using ``--no-clean`` will prevent
mock from rebuilding the environment)::

  mock -r epel-6-x86_64 --rebuild $BASEDIR/blockerbugs-$VERSION-$RELEASE.src.rpm
  cp /var/lib/mock/epel-6-x86_64/results/blockerbugs*.noarch.rpm $BASEDIR/.

Building a Koji Scratch Build
-----------------------------

The blocker tracking app isn't in the main Fedora repos, so we can't do official
builds but we can do scratch builds with this command::

  koji build --scratch dist-6E-epel-testing-candidate $BASEDIR/blockerbugs-$VERSION-$RELEASE.el6.src.rpm

Using Alembic
=============

`Alembic <https://alembic.readthedocs.org/en/latest/index.html>`_ is 'a lightweight
lightweight database migration tool for usage with the SQLAlchemy Database
Toolkit for Python.' and used to manage the database schema used with the application.

To install alembic, 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.

In many cases, alembic is able to determine the steps needed for upgrade and
downgrade through the inspection of SQLAlchemy classes. 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 Required 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