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 checks imports. It needs no API credentials and makes no Vatly calls.

Run tests

uv run pytest --cov

Tests use the real SDK with local HTTP and signed webhook fixtures. The SQLite driver tests cover storage, ownership, duplicate delivery, rollback and the outbox. No test changes a Vatly account. See offline examples for host tests.

Check formatting and types

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

CI runs tests and these checks on Python 3.10–3.14. Type checks also include the example storage driver.

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 and checks imports and py.typed. These commands do not publish anything.

Pinned SDK dependency

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

Documentation sync

Keep guides directly under docs/ and link each page from the overview. Pushes to main affecting docs/** notify vatly/vatly-docs. The notifier needs VATLY_DOCS_DISPATCH_TOKEN with Contents: write access to that repository. The sync uses an explicit frontmatter description when present, otherwise the page's introductory sentence.

Prepare a release

The published package is vatly-fluent-python; the import name is vatly_fluent. Publish the matching SDK version first, then Fluent, then Django, only after review and approval.

The workflow publishes only from a published GitHub release whose tag matches v plus the package version. Mark alphas as pre-releases. Pushing main does not publish. Restrict release access: trusted publishing needs no environment approval or PyPI token, and PyPI artifacts are public.

Storage contracts · Porting notes