Workflow

The following is a list of things you’ll probably need to do at some point while working on Normandy.

Running Tests

You can run the automated test suite with the following command:

py.test

In Python, to run the tests with code coverage run the following commands:

pip install pytest-coverage
py.test --cov-report html --cov-report term-missing --cov normandy
open htmlcov/index.html

JavaScript tests can be run with:

karma start

Linting

You will need to install Therapist for linting. If you have installed pre-commit hook linting will take place with every commit, however there may be times you want to run the linters manually.

To run the linters on all files that you have changed or added:

therapist use lint

To run the linters on all files in the repo:

therapist use lint:all

To run the linters and attempt to fix issues in files that you have changed or added:

therapist use fix

To run the linters and attempt to fix issues in all files in the repo:

therapist use fix:all

Updating Your Local Instance

When changes are merged to the main Normandy repository, you’ll want to update your local development instance to reflect the latest version of the site. You can use Git as normal to pull the latest changes, but if the changes add any new dependencies or alter the database, you’ll want to install any new libraries and run any new migrations.

If you’re unsure what needs to be run, it’s safe to just perform all of these steps, as they don’t affect your setup if nothing has changed:

# Pull latest code (assuming you've already checked out master).
git pull origin master

# Install new dependencies or update existing ones.
pip install -r requirements/dev.txt
yarn install

# Run database migrations.
python manage.py migrate

# Add any new action data (does not duplicate data).
python manage.py update_actions

# Update product details (does not duplicate data).
python manage.py update_product_details

# Update any new basic data (does not duplicate data).
python manage.py initial_data

# Build frontend files
yarn build

Building the Documentation

You can build the documentation with the following command:

# Enter the docs/ subdirectory
cd docs
make html

After running this command, the documentation should be available at docs/_build/html/index.html.

Adding New Dependencies

Normandy uses hashed requirements for all of our dependencies. This means that files in the requirements directory includes hashes that help verify that dependencies downloaded by pip haven’t been tampered with.

When adding a new dependency, you must include hashes for it. For packages that use wheels, you will have to include hashes for all of the platforms that the wheel supports, as they will all have different hashes. Tools like hashin can make adding these hashes easier.

Dependency’s dependencies should go in requirements/constraints.txt.

Preprocessing Assets with Webpack

We use Webpack to create asset bundles of static resources. These assets are only used for legacy actions, and can be ignored if you aren’t working with Firefox clients older than Firefox 66. You can build an asset bundle by running:

yarn build

You can also run the watch command to automatically rebuild your bundles as you make changes:

yarn watch

Running the command with --env.update-actions will automatically call manage.py update_actions when action code is built.

yarn watch --env.update-actions