Releases
pydelity’s releases are driven by commit messages. Nobody edits the version or the changelog by hand.
How a release happens
Section titled “How a release happens”- Changes reach
mainwith Conventional Commits messages. When a pull request is squash-merged, its title becomes the message, so the title must follow the format. - After each push to
main, release-please opens or updates a release pull request with the next version and itsCHANGELOG.mdentry. - Merging the release pull request sets the version in
pyproject.tomlanduv.lock, tags the commitvX.Y.Zand creates a GitHub release. - The GitHub release starts the
Releaseworkflow (.github/workflows/release.yml). It checks that the tag matches the package version, builds the wheel and sdist withjust buildand publishes them to PyPI. - The new tag starts the
Docsworkflow, which publishes the docs site with the new version. See The docs site.
The commit type decides the version:
| Commit message | Release |
|---|---|
fix: ... |
Patch, such as 0.1.0 → 0.1.1 |
feat: ... |
Minor, such as 0.1.1 → 0.2.0 |
feat!: ..., or a BREAKING CHANGE: footer |
Major |
Other types, such as docs:, test:, ci:, build(deps): |
None |
Check the version in the release pull request before merging it.
Make a release
Section titled “Make a release”- Wait for CI to pass on the release pull request, and read its
CHANGELOG.mdentry. - Merge it.
- Watch the
Releaseworkflow in the repository’s Actions tab. ThePublish to PyPIjob waits for approval if thepypienvironment requires it. - Check that the new version is on PyPI
and that
uv tool install --python 3.13 pydelityinstalls it. - Check that the docs site shows the new version.
If the Release workflow fails before publishing, fix the cause and re-run the
workflow from the Actions tab. PyPI never accepts the same version twice, so a
version that was published can’t be replaced, only followed by a new release.
The first release
Section titled “The first release”.release-please-manifest.json starts at 0.0.1, the placeholder that reserved
the name on PyPI, and there is no earlier release tag. The first feat: commit
on main makes release-please propose 0.1.0, tagged v0.1.0. Merge the survey
work with a feat: title (no ! and no BREAKING CHANGE: footer), then merge
the 0.1.0 release pull request once the release is approved.
Whether to yank the 0.0.1 placeholder on PyPI is a separate choice for the project’s PyPI owner.
One-time settings
Section titled “One-time settings”Publishing needs these settings outside the repository. Set them up before the first release.
PyPI Trusted Publishing
Section titled “PyPI Trusted Publishing”The Release workflow publishes with
Trusted Publishing, so no PyPI
token is stored anywhere. On PyPI, an owner of the pydelity project adds a
trusted publisher under the project’s Publishing settings:
| Field | Value |
|---|---|
| Owner | IDinsight |
| Repository name | pydelity |
| Workflow name | release.yml |
| Environment name | pypi |
The pypi environment on GitHub
Section titled “The pypi environment on GitHub”In the repository’s Settings → Environments, create an environment named
pypi. Under its deployment branches and tags, allow tags matching v*, since
the workflow runs on the release tag. You can also require a reviewer, so that
each upload to PyPI waits for someone’s approval.
GitHub Pages
Section titled “GitHub Pages”In the repository’s Settings → Pages, set the source to GitHub Actions.
Then, in Settings → Environments → github-pages, allow deployments from the
main branch and from tags matching v*, because the Docs workflow publishes
from both.
The release-please token
Section titled “The release-please token”release-please uses a fine-grained personal access token, stored as the
RELEASE_PLEASE_TOKEN_PYDELITY secret of the release-please environment. It
needs read and write access to this repository’s contents, issues and pull
requests. A release pull request made with the workflow’s own token would start
no CI, which is why a personal token is used. If the token expires or is
revoked, release-please fails until the secret holds a new one.