Skip to main content

Release process

LLenergyMeasure uses semantic versioning in the 0.x range while the project is pre-1.0. This page documents the versioning scheme, the two files that must stay in sync, and the step-by-step release procedure.

Versioning scheme​

  • Pre-1.0: minor version bumps (0.1.0, 0.2.0, ..., 0.N.0) mark significant capability milestones. Patch versions (0.N.1) are reserved for hotfixes.
  • 1.0.0 is reserved for the production-ready release. It is not tied to a calendar date and will be cut when the project meets the production-readiness bar.
  • Version management is manual - no automated bump tooling is used.

Feature work lands on main at the current version. Version numbers do not change on feature PRs - only on release commits.

Version sources​

Two files hold the version and must stay in sync:

FileFieldExample
pyproject.toml[project] version = "..."version = "0.9.0"
src/llenergymeasure/__init__.py__version__ = "..."__version__ = "0.9.0"

A mismatch between these two files is a bug. The build system reads pyproject.toml; the runtime API (llem --version, llenergymeasure.__version__) reads __init__.py.

Release steps​

  1. Bump the version in pyproject.toml

    Update the version field under [project]:

    [project]
    name = "llenergymeasure"
    version = "0.10.0"

  2. Bump the version in __init__.py

    Update __version__ in src/llenergymeasure/__init__.py:

    __version__ = "0.10.0"

    Both files must show the same version string.

  3. Update CHANGELOG.md

    Add an entry for the new version at the top of the changelog. Note key changes shipped since the previous release. The format is free-form but should be scannable.

  4. Commit

    Commit the three changed files with the message:

    chore: release 0.10.0

    This commit goes directly to main via the normal PR flow.

  5. Create and push the git tag

    git tag v0.10.0
    git push origin v0.10.0

    The tag must use the v prefix and match the version string exactly. Pushing the tag triggers the CI publication workflow.

  6. CI publishes to PyPI

    The release.yml workflow (.github/workflows/release.yml) triggers on push: tags: ["v*"]. It runs lint, tests, and then publishes the package to PyPI using uv build + uv publish. No manual upload is required.

Verifying a release​

After CI completes:

pip install --upgrade llenergymeasure
llem --version   # should show the new version

Check the GitHub Releases page - the tag should appear there automatically once the workflow completes.

Pre-1.0 vs post-1.0 policy​

The current 0.x scheme treats every release as potentially breaking. The stability contract documented in src/llenergymeasure/__init__.py applies: names in __all__ follow semver, internal names may change without notice.

When the project reaches 1.0.0, the guarantee tightens: breaking changes to public API require a major version bump. Until then, 0.x minor bumps may include breaking changes with a one-release deprecation window where practical.

See also​