Develop#

You need uv, make and git.

git clone git@github.com:PyCalendar/dashboard.pycal.org.git
cd dashboard.pycal.org
make dev    # Python, packages, git hooks, prompt recording, database
make run    # http://localhost:5000

make help lists all targets. make run starts the site with DEBUG=true, so that it registers its GitHub App without a setup code.

Settings for development#

make run reads .env. Start from the example for development:

cp .env.development.example .env

It names the settings that matter locally: a unique SITE_NAME for your development app, the OAuth app for signing in and your handle in SITE_ADMINS. .env.example lists every setting.

GitHub cannot deliver webhooks to localhost. To test them, make the site reachable through a tunnel, see Test the GitHub App locally with Tailscale.

Tests#

make test              # unit and API tests, on all processors, with coverage
make browser-install   # once: Chromium for Playwright
make browser-test      # browser tests, on all processors
make lint              # ruff
make docs              # the documentation; warnings fail
make prose             # the prose of the documentation (Vale)
make docker-test       # the image: healthy, with the setup code in the log
make docker-scan       # the image: no critical vulnerabilities with a fix (Trivy)

The tests run in parallel with pytest-xdist; JOBS=0 runs them in one process. They never use the network: GitHub is faked in tests/fakes/github.py.

  • tests/ are the unit tests of the services, the webhooks and the pages.

  • tests/test_public_json.py tests the JSON of the pages.

  • tests/browser/ start the site and click through it in Chromium.

The models#

After a change of the models:

make migrations

make test fails if a migration is missing. Never change a migration that may be applied somewhere; add a new one.

Continuous integration#

Every push runs these jobs in parallel: lint and the tests, the browser tests, the documentation with its prose and the workflows, and the build of the Docker image with its health check and the scan of Trivy. The image is pushed to ghcr.io only when all of them pass. For main, Sencho then deploys it and make check-live checks the live site, see Run the site.

Words that Vale does not know, such as names, go into .vale/styles/config/vocabularies/Dashboard/accept.txt.

CI publishes the documentation of main on GitHub Pages, at https://docs.dashboard.pycal.org/.