Skip to content

Contributing

Bug reports, fixes, features and documentation are welcome. For anything beyond a small fix, open an issue first to discuss it: the design notes say what the project aims at, and what it leaves out on purpose.

Setting up

You need Git, Python 3.12 or newer, and uv.

git clone https://github.com/abilian/abilian-analytics.git
cd abilian-analytics
make develop     # dependencies, pre-commit hooks, git configuration
make seed-db     # a local SQLite database, an admin account and a "Demo" project
make run         # http://localhost:5000, reloaded as you edit

Try it locally says what the seed script creates.

Checking your changes

make test             # the tests, on SQLite
make test-postgres    # the same on PostgreSQL (createdb abilian_analytics_test first)
make lint             # Ruff, formatting and type checks
make format           # fixes the formatting

Production runs PostgreSQL: run both test suites. The tests are in three layers, tests/a_unit, tests/b_integration (against a real database) and tests/c_e2e (through the app's routes).

Where things are

  • src/app/ has one package per area of the domain, each with its models and its logic: accounts, projects, sharing, filtering, tracking, reporting, housekeeping, and imports for the Umami and Matomo history. ADR 002 says why, and which may import which; a test checks it.
  • src/app/web/: the web app (Litestar), its routes, templates and the tracker, static/t.js.
  • migrations/: the Alembic migrations. A model change comes with its migration: uv run alembic revision --autogenerate, then check it.
  • src/app/cli.py: the abilian-analytics command.
  • mockups/: the pages' design reference.
  • scripts/: the development database's seed, the reports' benchmark, and the world map's build from Natural Earth's data.

The interface uses the Abilian Design System, copied into static/ads/ and templates/ads/ by uv run abilian-ds sync: never edit those files. The app's own styles are in static/theme.css. There is no front-end build step.

Sending a change

  1. Fork the repository and create a branch.
  2. Make your change, with its tests, and an entry in CHANGES.md if users will notice it.
  3. Commit with Conventional Commits messages (fix: …, feat(reports): …).
  4. Open a pull request against main.

The documentation

This site is built with Zensical from docs/src/:

make -C docs serve     # http://localhost:8000, rebuilt as you edit
make -C docs build     # into docs/site/
make -C docs deploy    # build, then deploy to analytics.lab.abilian.com (Hop3)

Write in plain English, in short paragraphs, one per line (no hard wrapping).

Conduct

Everyone taking part follows the code of conduct.