32 lines
1.6 KiB
Markdown
32 lines
1.6 KiB
Markdown
# AGENTS.md
|
|
|
|
REST API (Django + django-ninja) for managing the virtual domains, users and aliases that Postfix and Dovecot read
|
|
from the database. Deployed as mxapi.neuf.no.
|
|
|
|
## Setup and commands
|
|
|
|
Tools are managed by [mise](https://mise.jdx.dev) (Python, uv, prek) and Python deps by uv.
|
|
|
|
```sh
|
|
mise install # Python, uv, prek
|
|
uv sync # deps + dev tools
|
|
prek install # git hooks
|
|
uv run pytest # tests, must keep 100% coverage
|
|
prek run --all-files # ruff check, ruff format and file hygiene hooks
|
|
```
|
|
|
|
## Rules
|
|
|
|
- Use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages, e.g.
|
|
`feat: add alias search`, `fix(api): reject unknown domains`, `chore(deps): bump django`.
|
|
- Postfix and Dovecot query the `dpdapi_domain`, `dpdapi_alias` and `dpdapi_user` tables directly. Never rename
|
|
tables or columns, or change how values are stored (addresses are lowercased, passwords are SHA-512 crypt).
|
|
`tests/test_schema.py` guards this.
|
|
- Django stays on 5.2 LTS (and Python 3.14) until lynx has MySQL 8.4, which Django 6 requires.
|
|
- [mailadmin](https://git.neuf.no/edb/mailadmin) is the main API client. Don't change URLs, status codes or response fields it relies on;
|
|
`tests/test_mailadmin_contract.py` replays its calls.
|
|
- Test the API through HTTP in `tests/`, using pytest and the fixtures in `tests/conftest.py`.
|
|
- Keep coverage at 100%; `pytest` fails below it.
|
|
- Production-only deps (`gunicorn`, `mysqlclient`) live in the `prod` dependency group. Production settings come from
|
|
the environment (`dpdapisite/settings_prod.py`).
|