=======
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/.