Releasing¶
Package releases are deliberate maintainer actions. A branch push runs verification
and does not publish to PyPI. The existing release workflow runs only for version
tags matching v*.*.*; it requires the configured pypi environment and trusted
publishing permissions. Do not create a release tag merely to update repository
conventions.
Prepare a release¶
- Review user-facing change fragments in
CHANGES/. Use Towncrier typesfeature,bugfix,doc,removalandmisc. - Choose a version, update
pyproject.tomlandsrc/aiogram_cmds/version.pytogether, and render/review the changelog:
uvx towncrier build --draft --version X.Y.Z
uvx towncrier build --version X.Y.Z
- Install the locked development environment and run the contribution checks:
uv sync --all-extras --all-groups --frozen
uv run --frozen ruff check .
uv run --frozen ruff format --check .
uv run --frozen pyright
uv run --frozen pytest tests/unit tests/integration --cov=src/aiogram_cmds --cov-fail-under=80
uv run --frozen mkdocs build --strict
uv run --frozen bandit -c pyproject.toml -r src
uv run --frozen pip-audit
uv run --frozen python tools/check_version_tag.py
uv build
uv run --frozen twine check dist/*
- Verify the wheel and sdist in clean environments, including metadata/runtime
version equality,
py.typed, base installation without Redis, and supported aiogram dependency boundaries. Review the CI results and commit the release preparation through the usual review process.
Publish¶
Publication is a manual dispatch from a matching version tag. A branch push,
tag push or GitHub release alone does not publish to PyPI. The existing PyPI
Trusted Publisher remains bound to release.yml and the pypi environment.
After the reviewed commit and successful CI, create its vX.Y.Z tag. Build and
verify the wheel and sdist from that exact source, create SHA256SUMS containing
exactly those two filenames, and upload those files to the matching GitHub
release. Keep the independently verified digest of the manifest.
gh workflow run release.yml --ref vX.Y.Z -f manifest_sha256=<reviewed-manifest-digest>
The workflow checks tag/version equality, filenames, metadata and all artifact hashes before uploading those exact bytes through Trusted Publishing. It does not rebuild or substitute distributions. Confirm workflow success, compare PyPI hashes, and verify fresh standalone installation from PyPI afterward.
Never move release tags or replace published files. Correct a faulty release
with a new version. tools/deploy.sh and tools/deploy.ps1 are legacy tag
preparation helpers; they do not replace the explicit reviewed upload procedure.
Documentation¶
Documentation builds strictly on branch pushes and pull requests. Publishing to
GitHub Pages requires a manual Documentation workflow dispatch with deployment
enabled on main. Package release and documentation publication are separate
operations. Consuming applications own their deployment processes.