Release Guide

Release Guide

The repository is configured to publish a pure-Python wheel and source distribution to PyPI through GitHub Actions Trusted Publishing.

One-time PyPI setup

Create a PyPI account, enable two-factor authentication, and register a pending Trusted Publisher at:

https://pypi.org/manage/account/publishing/

Use these values:

Field	Value
PyPI project name	pytest-poolwatch
GitHub owner	Butterski
GitHub repository	pytest-poolwatch
Workflow filename	publish.yml
Environment name	pypi

The pending publisher can create the PyPI project on its first successful publication if the name is still available.

In the GitHub repository settings, create an environment named pypi. Requiring manual approval for that environment is recommended so publishing a GitHub Release does not upload by accident.

No long-lived PyPI API token or GitHub secret is required. The workflow requests an ephemeral OIDC token with id-token: write only for the publish job.

Official reference: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/

Before every release

1. Choose the version

Update both:

• project.version in pyproject.toml;
• __version__ in src/pytest_poolwatch/__init__.py.

Use a normalized semantic version such as 0.1.0.

2. Update documentation

• Move relevant entries from CHANGELOG.md's Unreleased section into the new version.
• Confirm README commands describe shipped behavior.
• Update Wiki compatibility, schema, and configuration pages if behavior changed.
• Update schema_version only for a breaking JSON-format change.

3. Run the complete validation

uv sync --locked --dev
uv run ruff check .
uv run ruff format --check .
uv run ty check
uv run coverage erase
uv run coverage run -m pytest
uv run coverage combine
uv run coverage report
uv build
uvx --from twine twine check dist/*

Inspect the wheel and source archive before the first release.

4. Verify installation from the wheel

Install into a fresh environment and confirm pytest discovers the plugin:

python -m pytest --help

The help output must include --poolwatch, --poolwatch-json, and --poolwatch-html.

Publish

1. Merge the release-ready commit to master.

2. Create an annotated tag matching the package version exactly:

   git tag -a v0.1.0 -m "pytest-poolwatch 0.1.0"
   git push origin v0.1.0

3. Create a GitHub Release for that tag and paste the matching changelog section.

4. Publish the GitHub Release.

5. Approve the pypi environment deployment if protection rules require it.

The workflow rejects a release whose tag does not equal v plus the version in pyproject.toml. It then builds both distributions, runs twine check, and publishes through PyPI Trusted Publishing.

Workflow: https://github.com/Butterski/pytest-poolwatch/blob/master/.github/workflows/publish.yml

Verify after publication

Open:

• https://pypi.org/project/pytest-poolwatch/
• https://github.com/Butterski/pytest-poolwatch/actions/workflows/publish.yml

Then install from the public index in a fresh environment:

python -m venv release-smoke
release-smoke/bin/python -m pip install pytest-poolwatch==0.1.0
release-smoke/bin/python -m pytest --help

On Windows, use release-smoke\Scripts\python.exe.

Run a one-test project with JSON and HTML output before announcing the release.

pytest plugin discovery

The distribution already has both pieces pytest expects:

classifiers = ["Framework :: Pytest"]

[project.entry-points.pytest11]
poolwatch = "pytest_poolwatch.plugin"

The pytest plugin list is compiled from active PyPI projects whose names begin with pytest- or pytest_. Publication and ongoing releases are therefore the important discovery steps; no separate pytest package submission form is needed.

If publication fails

Do not create a token as the first workaround. Verify the pending publisher's owner, repository, workflow filename, environment name, tag, and GitHub environment spelling. Trusted Publisher matching is exact.