Skip to content

Change control and versioning

Defines how HybridOps.Studio manages change, compatibility, and versioning for published interfaces.

Scope

This standard governs the stability expectations for:

  • CLI command surfaces (names, flags, exit codes, failure semantics)
  • runtime root and runtime layout semantics
  • evidence and readiness contracts (paths, minimum sets, schemas)
  • module spec contracts (schema, fields, semantics)
  • driver API contracts (request/response envelopes and semantics)
  • secret handling and redaction rules
  • plugin discovery and hook signatures (when declared stable)

Norms

  • Published contracts define behaviour that downstream users and automation may depend on.
  • Breaking changes MUST be explicit, reviewed, and documented.
  • Version identifiers MUST be stable and visible.
  • Behaviour that is not published as contract MAY evolve, provided it does not violate stable contracts.

Stable contract surface

The stable contract surface is any behaviour, schema, or interface that an external operator, consumer, or downstream automation can reasonably depend on across releases.

A change touches the stable contract surface if it impacts any of:

  • CLI command names, flags, exit codes, or failure semantics
  • runtime root precedence and runtime layout semantics
  • evidence path structure, evidence minimum set, or evidence schemas
  • readiness marker locations or schemas
  • module spec schema/fields and semantics
  • driver request/response envelopes and semantics
  • plugin discovery mechanism and hook signatures (when declared stable)
  • secret handling and redaction rules

Rule: If a change touches the stable contract surface, it MUST be treated as breaking unless it is purely additive and explicitly backward compatible.

Compatibility policy

Pre-1.0 releases (0.x)

  • 0.x releases MAY introduce breaking changes without deprecation windows.
  • Breaking changes MUST still be explicitly noted in release notes or change notes.
  • Contracts and standards SHOULD be treated as evolving unless explicitly marked Stable.

1.0 and later

  • 1.x releases MUST preserve backward compatibility for declared stable contracts.
  • Breaking changes MUST be scheduled for the next major version (2.0+), unless an exception is approved and documented.
  • Deprecation SHOULD be preferred over breaking changes.

Versioning rules

  • Major version changes indicate breaking changes to a declared stable contract surface.
  • Minor version changes introduce backward-compatible features or additive changes.
  • Patch version changes include bug fixes and internal refactors that preserve published contracts.

Breaking changes

Breaking changes MUST include:

  • a clear change note describing what changed and why
  • migration guidance (or an explicit statement that migration is required)
  • updated contract documents where applicable
  • an ADR where long-term stability is intended

Deprecation

  • Deprecated behaviour SHOULD be documented with the replacement path.
  • Deprecations SHOULD include a removal timeline where practical.
  • In 1.0 and later, deprecation SHOULD be used to evolve behaviour safely.

Alignment between docs and implementation

  • Contracts MUST describe implemented behaviour.
  • Behaviour not yet implemented MUST be marked Draft or excluded from Stable contracts.
  • Where implementation diverges, contracts MUST be updated or a change note MUST be issued.