Skip to content

Versioning & Compatibility

Canary Framework follows Semantic Versioning from 1.0.0 on. Versions before 1.0 were exploratory and made breaking changes freely.

What each number means

Release May contain
Patch — 1.0.x Bug fixes and documentation. No new public names.
Minor — 1.x.0 New features and deprecations. Existing code keeps working.
Major — x.0.0 Breaking changes, each listed in the changelog with a migration path.

There has been one exception: 1.1 changed two things used by code that drove the engine directly (advance / unwind were renamed, and stop() on a unit still in use no longer reclaims the whole graph); see What's New in 1.1.

The public API

The stability promise covers:

  • every name exported from canary_framework (listed in __all__), with the signatures and behaviour described in these docs;
  • the exception types raised in the situations the docs describe;
  • the lifecycle rules: dependency order, one run per unit and phase, the barrier between init and start, reverse-order reclamation, restart after stop().

It does not cover:

  • anything under canary_framework.core.* that is not re-exported from canary_framework;
  • names that start with an underscore;
  • the text of exception messages and notes;
  • the shape of Scope's record attributes — graph, dependents, tracks, known and keys. They are there for inspection and debugging, and may change in a minor release. Scope.instances, Scope.instance(), Scope.provide(), Scope.resolve() and Scope.key_of() are covered.

Extensions

canary_framework.test, canary_framework.config and canary_framework.web (with web.asgi, web.asgi.app and web.asgi.server under it) ship with the core and share its version number, but are provisional for now: until each is declared stable, its API may change in a minor release, with every change recorded in the changelog. The stability promise above covers the core only.

The core depends on no extension, and import canary_framework loads neither them nor their third-party dependencies.

Deprecation

A public name or behaviour is removed only in a major release, and only after at least one minor release in which using it emits a DeprecationWarning naming its replacement. Every deprecation is recorded in the changelog.

Supported versions

Only the latest minor release receives fixes, including security fixes. Upgrading within a major version is expected to be a drop-in change.

Python versions

Each release supports the Python versions listed on PyPI (currently 3.12 to 3.15). Support for a Python version that has reached its end of life may be dropped in a minor release; the changelog says so.

Releases

Releases are cut from main by pushing a vX.Y.Z tag. The notes for each release are the matching section of the changelog, followed by the list of merged pull requests.