Stability & Deprecation Policy

Parapet maintains a three-tier stability system so adopters know exactly what they can rely on in their SRE tooling and what may still evolve. This document enumerates every public module's tier, defines the semver promise, distinguishes breaking from additive changes, and specifies the full deprecation cycle.

Stability Tiers

Public API Surface Enumeration

Stable Modules

These modules carry the > #### Stable {: .info} callout. Their public function signatures, callback contracts, and telemetry event names will not change without a major-version bump and a full deprecation cycle.

Experimental Modules

These modules carry the > #### Experimental {: .warning} callout. Their APIs may change in a minor release; a single CHANGELOG entry will accompany any breaking change.

Internal (Excluded from Gate)

These modules are excluded from the mix verify.public_api gate. They have no stability guarantees and are not part of the public API surface.

Semver Promise

For Stable modules: Parapet follows Semantic Versioning 2.0.0.

• Major version bump (1.x.x → 2.0.0): May contain breaking changes. Every breaking change must first go through a full deprecation cycle (see below).
• Minor version bump (1.0.x → 1.1.0): New functions, new optional opts, new telemetry measurement/metadata keys may be added. Nothing is removed or renamed.
• Patch version bump (1.0.0 → 1.0.1): Bug fixes only. No API surface changes.

For Experimental modules: a single CHANGELOG entry noting the change before the release that contains it is the only commitment. Breaking changes may ship in a minor release.

What Counts as Breaking vs Additive

Breaking (requires major bump for Stable modules)

• Renaming or removing a public function or callback
• Changing the arity of a public function
• Changing the return type or shape of a public function
• Removing or renaming a telemetry event name under [:parapet, …]
• Removing or renaming a documented telemetry measurement key
• Removing or renaming a documented telemetry metadata key
• Changing the atoms in an outcome vocabulary (e.g., :delivered → :sent)

Additive (allowed in minor releases)

• Adding new public functions to a Stable module
• Adding new optional keys to an opts keyword list
• Adding new telemetry measurement keys to an existing event
• Adding new telemetry metadata keys to an existing event
• Adding new telemetry event families
• Adding new modules at any tier

Deprecation Cycle

Parapet uses a three-stage deprecation cycle for Stable-tier functions:

1. Soft deprecation — @doc deprecated: "Use X instead" added to the function. Appears in ExDoc as a deprecation notice. A CHANGELOG entry is included in the release. No compile-time warning. The replacement must already exist.

2. Hard deprecation — @deprecated "Use X instead" replaces the soft deprecation (or is added directly for a full-release cycle). Emits a compile-time warning at every call site. The replacement must already exist. Must remain in place for at least one minor release before removal is considered.

3. Removal — Only at a major version bump. The function is deleted. The deprecation window (steps 1–2) must have been complete before the major bump.

For Experimental modules: a single CHANGELOG entry in the release that contains the breaking change is sufficient. No multi-stage deprecation cycle is required.

Telemetry Contract

The [:parapet, …] telemetry event surface is frozen as of v1.0.0. Telemetry events are treated as part of the public API with the same semver guarantees as Stable module functions.

• Event names are frozen — renaming or removing any [:parapet, …] event name is a semver-major change.
• Measurement and metadata keys are additive-only — new keys may be added in minor releases; existing documented keys will not be removed or renamed without a deprecation cycle.
• No configurable :event_prefix — Parapet will never add a configurable :event_prefix option. All event names are static. This prevents the registry fragmentation seen when libraries allow event name customization (the Oban v2.10 lesson).

See the Telemetry Reference for the complete list of event families, measurements, and metadata keys.

Deprecation Register

This register tracks all current deprecations. It is updated at each release that introduces or advances a deprecation.

Parapet.SLO.define/2 deprecation window

Parapet.SLO.define/2 is in hard deprecation as of v1.0.0. Call sites will see a compile-time warning:

Parapet.SLO.define/2 is deprecated. Use a Parapet.SLO.Provider module instead.

The replacement is Parapet.SLO.Provider — define a module that implements the Parapet.SLO.Provider behaviour and register it via Parapet.attach/1:

defmodule MyApp.MySLOProvider do
  @behaviour Parapet.SLO.Provider

  @impl true
  def slos do
    [
      %Parapet.SLO.SliceSpec{
        name: :my_slo,
        objective: 99.9,
        # ...
      }
    ]
  end
end

# In your application start or Parapet.attach/1 call:
Parapet.attach(slo_providers: [MyApp.MySLOProvider])

Parapet.SLO.define/2 will be removed at the next major version bump.