Development and release

Set up the repository

Run commands from the repository root. On Linux or in an Amp orb:

.agents/setup

Setup installs uv 0.12.9 and Python 3.12, restores locked dependencies and runs Django's system checks. It needs no API credentials and makes no Vatly calls. It does not migrate your application's database or create test data.

Run tests

uv run pytest --cov
uv run python -m django makemigrations \
  --check --dry-run --settings=tests.settings

Tests apply real migrations to a temporary database and use local HTTP and signed webhook fixtures. They check ownership, CSRF, duplicate delivery, rollback and subscription state without changing a Vatly account.

SQLite is the default. The PostgreSQL-only concurrency test skips locally unless PostgreSQL is configured; CI runs it against PostgreSQL 17.

Check formatting and types

uv run ruff check .
uv run ruff format --check .
uv run mypy

Build and check the package

uv build
uv run twine check dist/*
uv run python scripts/check_package.py

The last command installs the built wheel in a fresh environment, migrates an empty database and checks imports and the py.typed marker. None of these commands publishes a package.

Supported versions

Pinned dependencies

pyproject.toml pins one exact vatly-api-python and vatly-fluent-python version from PyPI; uv.lock records their hashes. To move to new versions, change the pins, run uv lock, and run the full checks. Use a new alpha version when dependency behavior changes.

Prepare a release

The published package is vatly-django; the import name is vatly_django. Release matching versions in SDK → Fluent → Django order, only after review and approval.

The workflow publishes only when a GitHub release is published with a tag matching v plus the package version. Pushing main or running a local build does not publish. Restrict release access: there is no environment approval gate or PyPI token, and all PyPI artifacts are public.

Offline testing examples · Installation