The following is a list of things you’ll probably need to do at some point while working on Normandy.
You can run the automated test suite with the following command:
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
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
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
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:
You can also run the watch command to automatically rebuild your bundles as you make changes:
Running the command with
--env.update-actions will automatically call
manage.py update_actions when action code is built.
yarn watch --env.update-actions