Maintainer release guide

<- Back to home

This page is for maintainers of the behave-toolkit repository itself. It documents the release flow that creates the changelog update PR, the GitHub release, and the PyPI publication.

Release architecture at a glance

The release flow is driven by:

  • .github/workflows/release.yml

  • release-please-config.json

  • .release-please-manifest.json

  • CHANGELOG.md

The manifest file is part of the workflow state. Keep .release-please-manifest.json committed.

One-time repository setup

Before the release flow can work end to end, make sure the repository is configured like this:

  1. Enable Settings > Actions > General > Allow GitHub Actions to create and approve pull requests.

  2. Set the repository variable ENABLE_RELEASE_PLEASE=true when you are ready for the workflow to create release PRs.

  3. Optionally set ENABLE_RELEASE_AUTOMERGE=true if later release PRs should auto-merge after checks pass.

  4. Enable repository auto-merge if you want that workflow option to be effective.

  5. Configure a PyPI Trusted Publisher for the Release workflow before the first publish.

  6. Optionally add a RELEASE_PLEASE_TOKEN secret if you want CI workflows to run on Release Please PRs as well.

How a release is prepared

The workflow supports two entry paths:

  • push a branch named release/X.Y.Z

  • run the Release workflow manually with release_version=X.Y.Z

In either case, the workflow enters “prepare release PR” mode and asks Release Please to open or update a release PR targeting main.

What to review on the release PR

Before merging the generated release PR, review these points deliberately:

  • the version number is the one you intended to release

  • CHANGELOG.md reads well for external users

  • the package metadata and manifest updates look coherent

  • normal CI is green on the PR

For the first public release especially, edit or review the generated changelog carefully so it reads like a curated initial release, not like raw bootstrap history.

What happens after merge

Once the release PR lands on main, the same workflow enters “finalize release” mode.

It then:

  1. runs Release Please in release mode to create the tag and GitHub release

  2. checks out the created tag in the verify-release job

  3. validates the release tag with:

    • python -m mypy src tests test_support.py

    • python -m pylint src tests test_support.py

    • python -m compileall src tests test_support.py

    • python -m unittest discover -s tests -v

    • python -m sphinx -W --keep-going -b html docs docs/_build/html

  4. builds distributions with python -m build

  5. validates them with python -m twine check dist/*

  6. uploads the artifacts to the GitHub release

  7. publishes the package to PyPI through Trusted Publishing

  8. rebuilds and publishes the versioned GitHub Pages site from released docs tags

The published docs site keeps one directory per released documentation version, plus a latest/ alias that points to the newest release.

First release vs later releases

The workflow intentionally keeps 0.1.0 manual even if auto-merge is enabled. Later releases can use the optional auto-merge path once you trust the automation and the repository settings are in place.

Post-release checks

After the workflow succeeds, verify all of the following:

  • the GitHub tag exists

  • the GitHub release exists and contains the built artifacts

  • the new package version is visible on PyPI

  • the docs site shows the new version and latest/ points to it

  • the changelog on main reflects the published release

If the release included user-facing behavior changes, also make sure the docs site and README still reflect the new reality.

Troubleshooting release problems

No release PR was created

Check:

  • ENABLE_RELEASE_PLEASE=true is set

  • the event really matches release/X.Y.Z or workflow-dispatch input

  • GitHub Actions is allowed to create and approve pull requests

The release PR exists but other workflows did not run on it

If you need CI workflows to run on Release Please PRs, provide RELEASE_PLEASE_TOKEN instead of relying only on the default github.token.

GitHub release was created but PyPI publish failed

Check the PyPI Trusted Publisher configuration first. The publish job uses pypa/gh-action-pypi-publish with OIDC, so the repository, workflow, and environment must match what PyPI expects.

The built artifacts look wrong

Reproduce locally with:

python -m build
python -m twine check dist/*

That mirrors the final packaging validation step from the workflow.

Suggested maintainer habit

Keep the release mechanics boring:

  • merge only green release PRs

  • read the generated changelog every time

  • treat .release-please-manifest.json as workflow state, not as disposable noise

  • keep this guide updated whenever the workflow changes