Release Hermit#

Use one source revision for the Git tag, GitHub release and PyPI distributions. A GitHub release alone does not update the package installed by pip.

1. Prepare the release#

  • Pull the latest main and choose the version and included changes. Preserve unrelated local work.

  • Update pyproject.toml, hermit/__init__.py, CITATION.cff, the README version badge and docs version labels. Keep historical release references and upstream package versions unchanged.

  • Move the accumulated changelog under the new version and planned release date, leaving an Unreleased section. Explain breaking changes and link migration instructions.

  • Draft the GitHub notes: Highlights by feature, Breaking Changes, What’s Changed, New Contributors and Full Changelog. Check contributor attribution against the project’s release policy and review the generated list.

2. Validate the source and distributions#

Run the contribution checks, affected method tests, the offline Quick Start and the strict documentation build. Record failures, skips and platform limits. Linux sandbox checks need a Linux environment; a successful macOS build does not verify them.

Run the Release checks and PyPI workflow manually on the candidate revision for Linux core/sandbox checks, distribution builds and an installed-wheel smoke. Manual dispatch validates without publishing.

In a clean source checkout and a packaging environment with build and twine installed:

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

Use a fresh dist/ directory for each release. Check that the wheel and source distribution contain all bundled templates and methods, including hidden metadata and resource files, and no credentials, run artifacts or caches.

Install the wheel into a separate, clean environment. Check its installed version and hermit --help, then run the offline Quick Start through check, train, evaluation and deployment. Test from outside the source checkout so it cannot hide missing packaged files. Optional method dependencies still require their documented installation.

3. Publish the tested revision#

Commit the release preparation and validate the final revision. Create and push its vX.Y.Z tag. The .github/workflows/release.yml workflow verifies that the tag matches the package version, reruns the Linux checks, then publishes the built wheel and source distribution to the existing hermit-harness PyPI project.

One-time setup: a PyPI project maintainer adds a GitHub Trusted Publisher with owner Infini-AI-Lab, repository hermit, workflow release.yml and environment pypi. The workflow uses short-lived credentials rather than a stored PyPI token. Wait for publication to succeed, then publish the reviewed GitHub release notes for the same tag.

For a manual publication instead, upload the matching, tested distributions with Twine:

python -m twine upload dist/*

Authenticate through the publishing tool; keep credentials out of source files, command arguments and shared logs. See PyPI Trusted Publishing for the automated setup. Creating a GitHub release by itself does not trigger this tag-based PyPI workflow.

Published versions are immutable. Correct a bad release with a new version rather than replacing its files or moving its tag.

4. Verify the published release#

In another fresh environment, install the exact version from PyPI, check the installed version and command, and run the offline smoke again. Confirm that the GitHub tag, release notes, package metadata and documentation agree. Update the README News announcement and share the release once public installation works.

The maintainer confirms the release scope, notes and publication. An agent can prepare the changes, run the checks, build the distributions and report any remaining limits; commit, tag, push and publication follow the maintainer’s instructions.