Skip to content
You're reading the docs for DRE 0.12 (v0.12.2). This page for 0.13

Stability contract

This contract applies from DRE 1.0. DRE 0.12 remains pre-1.0. Before 1.0, patch releases preserve projects; a minor release may break them with release notes and migration guidance. See New in 0.12 and Updating DRE before crossing that boundary.

From 1.0, a supported project continues to validate and run within the same core major version, using compatible, pinned plugins. The compatibility promise covers:

  • Documented project YAML keys, types, defaults, layering and template functions and filters.
  • Documented CLI commands, flags, selector semantics, registered diagnostic codes and exit codes.
  • Versioned machine-readable outputs: manifest and run results, validation JSON, JSON log events, and scheduled occurrence documents. Consumers must check the document’s schema identifier and tolerate additional optional fields.
  • Protocol 1 framing, message semantics and capability negotiation. Plugins and SDKs have their own package versions; negotiate protocol support rather than comparing their package version with core’s version.
  • Documented configuration for first-party plugins within each plugin’s compatible major version. Install and pin the plugin versions required by the project; upgrading core does not implicitly upgrade those independent contracts.

An incompatible change to a covered interface requires a new major version of its owning package, with migration instructions. Additive features may arrive in a minor release. Deprecated configuration keeps working throughout the same major version, warns with its replacement, and is listed in upgrade guidance before removal in a later major version. Security fixes may tighten previously unsafe behavior; release notes identify the effect and the required action.

Rust crates such as dre-core, dre-template and dre-plugin-host are implementation components, not a stable embedding API. Their public Rust symbols may change independently of project compatibility. The plugin SDK’s Rust/Go APIs follow their own package versions; use the wire protocol as the integration boundary for independently implemented plugins.

Human-readable log text, progress output, diagnostic wording and generated directory internals are not machine interfaces. Use registered error codes and documented JSON fields instead of parsing prose or guessing file layouts. Output bytes, spreadsheet styling and PDF pagination may change after renderer, font or dependency fixes; pin those dependencies when exact output reproduction matters. Database behavior and externally managed drivers, permissions, mounted filesystems and destination services remain outside DRE’s control.

Read release notes for core and each changed plugin, keep the old binary and dependency lock, then validate and preview representative reports. Use dre test for data checks and dre build when those checks must gate delivery. Rehearse with non-delivering targets before production. For pre-1.0 changes, follow the specific migration guide rather than applying the 1.0 promise retroactively.