Development Tasks

Git Branching Strategy

We’re using a slightly modified version of Vincent Driessen’s A highly successful git branching model and the associated git-flow tool (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 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 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 using Compass. 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 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