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, andimportsfor 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: theabilian-analyticscommand.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¶
- Fork the repository and create a branch.
- Make your change, with its tests, and an entry in
CHANGES.mdif users will notice it. - Commit with Conventional Commits messages (
fix: …,feat(reports): …). - 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.