Releasing¶
This maintainer checklist describes deliberate releases. Repository pushes and
documentation builds do not publish a package. The current release candidate is 0.3.0.
- Review compatibility, recovery/storage schema changes and dependency boundaries. Check the supported Python/aiogram and real-Redis jobs, plus optional navigation integration against a compatible peer revision.
- Review the fragments in
CHANGES/. Preview withuv run --no-sync towncrier build --draft --version 0.3.0, substituting the intended release version when preparing a future release. - Set the intended version in
pyproject.toml, the authoritative source. Runtime version reporting reads installed distribution metadata. Refreshuv.lockand sync the environment before checking the version. - Run the quality, security and artifact checks, including
uv run --no-sync python tools/check_version_tag.py. Review dependency audits on Python 3.11+ and resolve findings rather than committing an ignored baseline. - Assemble the changelog with Towncrier only after reviewing its draft, then rebuild wheel/sdist and verify their metadata and isolated installations.
- Commit the reviewed release changes. Create a matching tag only when a release
is authorized; the version tool checks
GITHUB_REFwhen run on a tag. - Publish aiogram-nav first when preparing matching releases. The optional
navextra requires a compatible aiogram-nav distribution on PyPI. - Create the matching GitHub release with the reviewed wheel, sdist, release
notes and a
SHA256SUMSmanifest containing exactly those two artifact names. Keep the independently verified SHA256 digest of the manifest outside the release assets. Configure the PyPI Trusted Publisher for this repository'spublish.ymlworkflow andpypienvironment before dispatching publication. - Dispatch publication against the matching tag, using the reviewed manifest digest rather than a digest newly downloaded from GitHub:
gh workflow run publish.yml --ref v0.3.0 -f manifest_sha256=<reviewed-manifest-digest>
The workflow verifies tag/version equality and exact artifact filenames and
hashes, checks metadata, and publishes those downloaded artifacts through
PyPI Trusted Publishing. It does not rebuild or substitute distributions.
10. Verify the published file hashes and availability on PyPI. Install both the
standalone package and [nav,redis] in fresh environments from the index;
confirm the optional integration resolves without source checkouts.
Substitute the actual release version consistently. Do not add credentials, generated security reports or build output to commits. Repository pushes never trigger the manual publication workflow.
Published dependency freeze¶
Release CI and artifact checks resolve coordination and optional navigation from
the package index. Do not add local peer sources or sibling checkout requirements
to the release lock. tools/check_artifacts.py without --peer verifies this
registry-only path; explicit --peer remains available for separately identified
local experiments and is not release evidence. Publish coordination before
navigation, and navigation before idle, so every advertised extra resolves.