Developer Setup

It is strongly encouraged to create a new virtual environment (or conda environment) for this project if you are working on this alongside factotum.

Although the two share similar packages, there is no guarantee the versions of these packages will align. In addition, the nature of both the separation and dependency of factotum and factotum_ws will be more intuitive if considered in the context of isolated environments.

Configuration

The settings for this Django application can be set by either including a .env file in the root of the repository or by setting environment variables. Environment variables take precedence; if a variable is set both in a .env file and in the environment, the environment variable will be used.

.env

A .env file is a collection of simple key-value pairs. It is just a text representation of environment variables. Create a copy of template.env and name it .env. Edit the variables so that, for example, the Django app can communicate with your MySQL instance.

Environment variables

You also have the option to use environment variables via export on Unix like systems or set on Windows systems. This is useful if you have many applications sharing the same configurations or want to avoid storing the plaintext of secrets (e.g. SQL passwords).

Installing dependencies

As usual, dependencies can be installed with pip:

pip install -r requirements.txt

You will notice that factotum is listed as a dependency in requirements.txt:

...

git+https://github.com/HumanExposure/factotum.git@dev#egg=dashboard

This is because factotum_ws is dependent on the model definitions, fixtures, and migrations of the factotum/dashboard app. A minimal packaging of the factotum/dashboard app is installed when installing this dependency.

Keeping in sync

Note the ...@dev in this line of requirements.txt; by issuing the pip install command, pip will install the minimal packaging of the factotum/dashboard app at its current state in the dev branch from GitHub.

The HEAD of the dev branches in both of these repositories are to always be compatible with each other. On the same token, the HEAD of this repository may not be compatible with a stale installation of factotum/dashboard. A reinstallation of requirements.txt will get you back in sync.

To perform a reinstallation, include the -I flag in your pip command:

pip install -I -r requirements.txt

Developing against a different branch

Sometimes a feature in a PR branch of factotum/dashboard may break the functionality of factotum_ws. You will need to make an accompanying PR for this branch to resolve these issues. Keep in mind, though, you need to develop against that branch, not dev.

Changing requirements.txt

A simple way to get that branch into your development environment is to change the ...@dev portion of the requirements.txt to point to the correct branch and reinstall the requirements. This change would not be checked into GitHub. Once the PRs are approved and merged, dev will now point to the correct branch again.

Installing a local copy

Alternatively, you can install your local copy of factotum/dashboard. You will see that there is a setup.py file at the root of the factotum repository. This is what pip uses to install this package. While in the directory containing this file, running...

pip install .

...will install this local version of factotum/dashboard rather than going to GitHub.

Why?

This may seem cumbersome since dev is a fast moving branch. The benefits become apparent when a git branching strategy is used.

Say factotum has a release branch release-1.0. Since this is a release branch, no new features will be made and only bugfixes are introduced. When the release-1.0 branch is complete and ready for production, it is merged into master with a v1.0 tag.

Instead of tracking ...@dev, we can track [email protected] for testing to ensure no code-breaking changes are introduced. Feature branches could be dependent on the latest v1.x tag in production. Beta branches could track [email protected].

This repository has the freedom of creating its own features, release schedule, and versioning without being too tied up with the factotum release schedule if desired. In short, we're utilizing git as a package versioning system.