Versioning & stability

Pyrula follows Semantic Versioning. The packages (pyrula, pyrula-workflows, pyrula-agents, pyrula-kafka, 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 release notes.
• 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.

Supported 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"]  # "stable"

Every surface pyrula-agents and pyrula-workflows ship is supported, as is pyrula.parallel (par_map and its errors), which lives in its own module rather than the top-level pyrula namespace: the public name and the expected return shape are preserved, and breaking changes happen only through a documented contract change and a changelog entry. There is no experimental tier. The adapter guarantee matrix states what each integration guarantees, capability by capability; the serving guide covers the HTTP layer and the run browser, which is deliberately small: a read-only view of runs and their events for local development, not a dashboard. The Kafka client guarantees and Kafka runtime guarantees pages do the same for the Kafka surfaces.

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. For ordinary code changes, see Versioning and deploys.