Contributing

Contents

Setup

Create a Python 3.11 virtual environment.

Set up the git pre-commit hook:

pip install pre-commit
pre-commit install

Backend

Change to the backend directory:

cd backend

Install development dependencies:

pip install pip-tools
pip-sync requirements_dev.txt

Run database migrations:

./manage.py migrate

If you don’t have an instance of Pelican backend, create its database and load fixtures:

createdb pelican_backend
gunzip -c backend/tests/fixtures/pelican-backend.sql | psql pelican_backend

Frontend

Change to the frontend directory:

cd frontend

Install development dependencies:

npm install

Development

In one terminal, start the backend server:

cd backend
./manage.py runserver

In another terminal, start the frontend server:

cd frontend
npx vue-cli-service serve

Backend

The Django project is made up of two apps:

  • api: Serves API requests

  • exporter: Generates the exports to Google Docs

API documentation

See also

API

If you edit views.py, regenerate the OpenAPI document by running the server and:

curl http://127.0.0.1:8000/api/schema/ -o docs/_static/openapi.yaml

Pelican backend integration

Pelican backend’s database is treated as a read-only legacy database, with managed = False in all model’s Meta class, and with a DATABASE_ROUTERS setting that routes queries to its database.

To update backend/api/models.py following changes to Pelican backend’s database schema:

  • Run python backend/manage.py inspectdb > backend/api/models.py

  • Replace comments at top of file

  • Replace models.DO_NOTHING with on_delete=models.CASCADE

  • Dataset.meta: Add blank=True, default=dict

  • DatasetFilter.dataset_id_original: Rename to parent, add related_name="children"

  • DatasetFilter.dataset_id_filtered: Rename to dataset, add related_name="filtered"

  • ProgressMonitorDataset.dataset: Add related_name="progress"

  • ProgressMonitorItem.item: Rename to data_item

  • Report.type: Change TextField to CharField, add max_length=255, and remove # This field type is a guess.

Learning

Testing

Backend

./manage.py test

Frontend

npm run test

Run linters:

npx vue-cli-service lint

Production

Prepare a production build:

npx vue-cli-service build

This sets the NODE_ENV environment variable to "production". To override this default, use:

npx vue-cli-service build --mode development