======= Develop ======= You need `uv `_, ``make`` and ``git``. .. code-block:: shell 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: .. code-block:: shell 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``. :file:`.env.example` lists every setting. GitHub cannot deliver webhooks to ``localhost``. To test them, make the site reachable through a tunnel, see :doc:`github-app-tunnel`. Tests ===== .. code-block:: shell 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: .. code-block:: shell 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 :doc:`run-docker`. 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/.