Skip to content

API Stability Policy

Status: Active as of v3.0.0. This policy defines what MineProductivity guarantees about its public API, how those guarantees map to version numbers, and how APIs are deprecated. It is the binding contract behind docs/PUBLIC_API.md.

1. Versioning scheme

MineProductivity follows Semantic Versioning 2.0.0: MAJOR.MINOR.PATCH.

  • MAJOR - incompatible public-API changes (removal, renamed/retyped symbols, changed semantics, removed packages).
  • MINOR - backward-compatible additions (new packages, new public symbols, new optional interface hooks, new extras).
  • PATCH - backward-compatible bug fixes with no API change.

The software version is independent of the architecture document version (v1.0, locked).

2. What is public

A symbol is public if and only if it is listed in the __all__ of a package's top-level __init__.py (mineproductivity.<package>). Everything else - _-prefixed modules, names absent from __all__, test fixtures, scripts/, examples/ - is private and may change in any release without notice, even if it happens to be importable.

The public surface is enumerated in docs/PUBLIC_API.md.

3. Guarantees within a MAJOR line

For the lifetime of a major version (e.g. all 3.x):

  1. No public symbol is removed or renamed.
  2. No public function/method signature changes incompatibly; no public dataclass field is removed or retyped incompatibly.
  3. Registry object names, decorator names, and entry-point group names (PUBLIC_API §2–4) do not change.
  4. Interface ABCs keep their abstract-method signatures; new abstract methods are never added within a major (that would break existing subclasses). New optional hooks with safe defaults may be added in a MINOR.
  5. Deterministic outputs of shipped models remain stable, except for disclosed bug fixes (recorded in CHANGELOG.md).

Anything requiring a violation of the above is deferred to the next MAJOR.

4. Deprecation policy

Public API is never removed abruptly. To remove or change a public symbol:

  1. Announce in the CHANGELOG.md "Deprecated" section, naming the replacement and the earliest version in which removal may occur.
  2. Warn at runtime with DeprecationWarning where feasible, for at least one full MINOR release in which the symbol keeps working.
  3. Remove only in a subsequent MAJOR release, documented under "Removed (BREAKING)" with a migration note.

A deprecation must ship at least one MINOR before the MAJOR that removes it, so downstream users always have a working, warned-about transition window.

5. Precedent: the v3.0 removals

The v3.0 removal of seven empty placeholder packages (ADR-0013) is the reference example of a compliant breaking change: the change was gated behind a MAJOR bump, documented under "Removed (BREAKING)" in CHANGELOG.md, and accompanied by a migration guide. (These packages shipped no code and had no importers, so no runtime deprecation window was required - there was nothing functional to deprecate.)

6. Plugin & entry-point compatibility

  • Entry-point group names are part of the public API (§3.3) and are stable within a major.
  • Plugins should bound their framework dependency by major (mineproductivity>=X,<Y) and declare the same range in their registry.VersionRange gate, widening only across majors they have verified.
  • The framework's discovery is isolated: an incompatible plugin is skipped, never fatal, so a host stays stable across mixed plugin versions.

7. Supported versions

Which releases and Python versions receive fixes is defined in SUPPORTED_VERSIONS.md.