Versioning & stability

Pyrula follows Semantic Versioning. The packages (pyrula, pyrula-workflows, pyrula-agents, pyrula-kafka, pyrula-connectors, pyrula-pipelines, pyrula-cloud-client) release together at matching version numbers. Install matching minors across packages; the suite is tested as a set, not in mixed-version combinations.

Before 1.0

While the suite is in 0.x, the public API is still settling:

• A minor bump (0.4 to 0.5) may include breaking changes. Anything that breaks is called out in the changelog.
• A patch bump (0.4.1 to 0.4.2) is fixes and additions only, no breaking changes.

Pin a minor (pyrula~=0.4.0) if you need a stable target while evaluating.

Stable vs experimental surface

Not every public symbol carries the same promise. Each runtime package classifies its exports, exposed as a map you can read at runtime:

from pyrula.workflows import STABILITY

STABILITY["RunEvent"]            # "stable"
STABILITY["InlineWorkflowRunner"]  # "experimental"

• Stable symbols: we preserve the public name and the expected return shape, and avoid breaking changes outside a documented contract change.
• Experimental symbols: shape may change between minors. Useful, but pin a version if you depend on one.

Durable run compatibility

Durable workflows persist an event log tagged with EVENT_SCHEMA_VERSION. Replaying a run written by an incompatible engine version raises SchemaVersionMismatch rather than silently misreading the log. Drain or migrate in-flight runs across an event-schema bump; ordinary code deploys that do not change the schema replay cleanly.