Stability policy

RelPrim follows Semantic Versioning from 1.0.0 on. This page describes what you can depend on, and what may change in which kind of release.

What is covered#

The stable API is what the API reference lists as public:

• names exported from relprim and from the optional integration modules;
• documented parameters, defaults, attributes, return types and raised exceptions;
• documented runtime semantics, such as retry counting, fallback ordering, idempotency statuses and cancellation behavior;
• EventType values and the event payload and report metadata keys documented in Structured events;
• the SQLite event-store schema: databases created by an earlier 1.x release remain readable by later 1.x releases.

What a release may contain#

Release	May contain
Major (2.0.0)	Any breaking change to the covered API.
Minor (1.1.0)	New features, new optional parameters with defaults, new event types, new payload or metadata keys, new supported Python versions, deprecations, and dropping Python versions that reached end of life.
Patch (1.0.1)	Bug fixes and documentation.

A minor or patch release may change behavior that clearly contradicts the documentation or is plainly unintended. Such fixes are called out in the release notes.

Deprecated APIs emit DeprecationWarning for at least one minor release before they are removed in the next major release.

What is not covered#

• Names starting with an underscore, and anything not in an __all__ list.
• The submodule in which a core name is defined. Import core names from relprim.
• Exception messages, repr() output, validation reason wording and ExecutionError.message contents.
• Timing details such as exact durations, jitter values and scheduling order between concurrent operations.
• The dev extra and the contents of the test suite.

Events and metadata#

Event identifiers and documented keys are treated deliberately. They are never renamed or removed outside a major release, and their value types do not change. New keys and new event types can appear in minor releases, so consumers should ignore what they do not recognize.

This applies to the keys documented in Structured events, the OpenTelemetry attribute names derived from them, and the SQLite schema.

Optional integrations#

The names exported by relprim.opentelemetry, relprim.jsonschema and relprim.pydantic are covered like the core API. Each extra declares the supported range of its dependency, and the lower bound of each range is tested. The core package never imports an optional dependency.

Typing#

RelPrim ships inline type information (PEP 561). Type annotations of the public API are part of the contract, but improvements that make inferred types more precise may land in minor releases. Such changes can surface new errors or unused # type: ignore comments under strict type checking without being considered breaking.

Supported Python versions#

RelPrim supports Python 3.11–3.14. Each supported version is tested with the base install and all optional extras.