Skip to content

Deprecation policy

How features get removed from TLSStress.Art without surprising customers who built workflows on top of them.

The contract

Audience Minimum notice
API endpoints (dashboard REST, K8s manifest contracts, OOBI canonical addressing, signed envelope schema) 2 minor releases + 6 calendar months, whichever is longer
Config flags / env vars 1 minor release
CLI flags 1 minor release
MÓDULO X.Art removal (an entire module retiring) 3 minor releases + 9 calendar months
Test Kind retirement 2 minor releases
Documentation paths Best-effort; redirects when feasible
Patent-claim-anchored surfaces (#1..#25) Never silently — always via ADR + explicit deprecation announcement

"Minor release" = a vX.Y.0 bump where Y increments. "Calendar months" run from the release that first marked the feature deprecated.

The mechanics

A feature goes through four phases:

  ┌──────────┐    ┌────────────┐    ┌──────────┐    ┌──────────┐
  │  Active  │ →  │ Deprecated │ →  │  Frozen  │ →  │ Removed  │
  └──────────┘    └────────────┘    └──────────┘    └──────────┘
                       │                │
                       │                └── No new feature work; bug fixes only
                       └── Marked in code + docs + CHANGELOG
Phase Code state User state Trigger to next
Active Works normally Use freely An ADR or RFC marks the feature for deprecation
Deprecated Works normally; emits a runtime warning + appears in Deprecated section of CHANGELOG.md; doc carries a callout Migrate to the replacement — listed in the deprecation notice Notice period elapses
Frozen Works normally; receives security fixes only; no new features land on it Migration deadline approaches Removal release ships
Removed Code path deleted Calling the removed surface returns a clear error message pointing to the migration doc —

What MUST appear when a feature is deprecated

  1. CHANGELOG.md entry under the Deprecated heading for the release where deprecation begins, naming:
  2. The deprecated surface
  3. The replacement (or "removed without replacement" if applicable)
  4. The earliest release where removal becomes possible
  5. A link to the migration doc
  6. Code annotation wherever practical:
  7. Go: // Deprecated: <reason>; remove no earlier than vX.Y.0
  8. TypeScript: /** @deprecated <reason>; remove no earlier than vX.Y.0 */
  9. Config files: comment header # Deprecated as of vA.B.C — remove no earlier than vX.Y.0
  10. Runtime warning when the deprecated surface is exercised (log line, dashboard banner, or one-shot stderr — choose what the user will actually see)
  11. Migration doc under docs/migrations/ (or a referenced section in the relevant operator guide) showing the before / after pattern
  12. ADR delta if the feature anchors a patent claim or shipped ADR — supersede the prior ADR with a new one citing this policy

Removal-day checklist

Before the PR that removes the deprecated code lands:

  • Notice period from the policy table has elapsed
  • Migration doc has been published for the full notice window
  • CHANGELOG.md Removed entry drafted for the release
  • Tests that exercised the removed surface have been migrated or deleted
  • Public-facing materials (Investor Deck KPI counts, marketing page, datasheet) that referenced the removed feature have been updated in the same release
  • Search across the repo for residual references (use grep -rE "<removed-surface>") returns empty after cleanup

Exceptions

Two exceptions to the notice period, both rare:

  1. Security-driven removal — the feature is itself the vulnerability. Notice may compress to 1 minor release + 30 days, with explicit security-advisory disclosure. ADR required.
  2. Patent-prosecution-driven removal — a filing requires the feature to be retired before the application proceeds. Notice may compress; the maintainer announces in CHANGELOG with a reference to the controlling ADR.

Both exceptions are documented in the release notes; neither is ever silent.

Why this matters

Customers building procurement-grade workflows on TLSStress.Art need to know how much migration runway they get. A 6–9 month floor is the minimum a regulated-sector ops team can fit into a change-management calendar. Anything shorter forces them to fork.

For audit / valuation purposes, the existence of this policy is itself a signal — solo projects don't write deprecation policies.

Last verified against shipping code: v3.7.0 (2026-05-12).