Development setup

Note

Update on 2013-08-23: The advice below was written before the configuration rewrite of Navigator mid-August 2013. haphut no longer uses another repository for testing. The nodeenv advice is still valid. Here's another, yet compatible approach to control npm install -g.

haphut's environment

haphut uses separate local repositories for development and testing. The former are run-of-the-mill GitHub clones. The latter are clones of the local development repositories.

The upsides of this setup include the cleanliness of the development repo and the easy separation of the testing configuration from the official upstream. The downside is the extra effort it takes to commit every little thing and to merge it on the testing repo before testing can commence.

Modifications are often needed for local testing, for example to include API keys, to localize project settings or to refer to localhost servers. A separate branch local_settings in the testing repo is used for such changes. Commits in local_settings are the only commits unique to the testing repo apart from necessary merge commits. The merges occur when feature branches from the development repo are merged with local_settings.

Additionally, the testing repo has its own virtualenv with an integrated nodeenv. That way the system files are kept clean and under the control of the system package manager. Furthermore, tools like Grunt remain available without complicated paths when installed "globally" inside the virtualenv.

Setup

1. Create repositories

In this example, programming projects reside in the directory ${HOME}/prog so create git repositories there.

cd "${HOME}/prog"
git clone "[email protected]:${GITHUB_USER}/navigator-proto.git"
git clone navigator-proto navtest

2. Set up virtualenv and friends

Arch Linux has python set to Python 3.x and python2 set to Python 2.7. Other Python packages in the package repositories follow the same naming pattern. Modify these instructions to match your distribution.

Let's install virtualenv and virtualenvwrapper from the system package repositories for ease of maintenance. That way we do not need to change the PATH variable either.

# virtualenvwrapper works on both Pythons.
sudo pacman -S python-virtualenvwrapper

Add the following into ${HOME}/.bashrc or ${HOME}/.profile or somewhere similar:

# Where the project dependencies are stored.
export WORKON_HOME="${HOME}/.virtualenvs"
# Where the programming projects lie. Not a necessary variable for our project.
export PROJECT_HOME="${HOME}/prog"
# There's also virtualenvwrapper_lazy.sh available.
source /usr/bin/virtualenvwrapper.sh

As our projects use Python 2.x, we need to initially be careful to use the right version. Create the environment and install nodeenv and Node.js in it.

mkvirtualenv --python=python2 navtestenv

## workon was run automatically by mkvirtualenv.
#workon navtestenv

# Note, this calls the pip inside navtestenv. The same program outside
# navtestenv is called pip2.
#
# By default, pip installs globally which in this context means navtestenv.
pip install nodeenv

# Use navtestenv for nodeenv as well. Install Node.js there.
nodeenv --python-virtualenv

Restart your shell and install project dependencies and tools.

workon navtestenv
cd "${HOME}/prog/navtest"

# By default, npm installs inside the current directory.  Add "--global" for
# navtestenv.
npm install
npm install --global grunt-cli testem coffee-script

# Robot installation.
#
# Again, outside of navtestenv the Python used here would be named python2.
python bootstrap.py --version 2.1.1
bin/buildout

3. Configure testing repository

Now it's time to add API keys and so on.

cd "${HOME}/prog/navtest"
git checkout -b local_settings master

# Change the configuration and commit each cohesive change separately.

Workflow

When the setup is ready, the coding may commence. Let's try creating a new feature.

cd "${HOME}/prog/navigator-proto"
git checkout -b magic_feature

# Fervent coding and commiting.

In another terminal, run the tests.

workon navtestenv
cd "${HOME}/prog/navtest"

git fetch --all
git checkout -b ls_magic_feature local_settings
# This might cause conflicts:
git merge origin/magic_feature

grunt test

After further commits in the development repo for magic_feature, run the tests again in the testing terminal.

git fetch --all
# This might cause conflicts:
git merge origin/magic_feature

grunt test

After an upstream update

When master branches in the upstream and the development repos have changed, remember to pull master into the testing repo and rebase local_settings onto it.

cd "${HOME}/prog/navtest"
git checkout master
# Remember, no developing in the testing repo. This should be a fast-forward.
git pull
# This might cause conflicts:
git rebase --onto master --root local_settings