Feature deprecation / end-of-life communication

patterns specs/patterns/deprecation.kmd

Canonical pattern for communicating a feature's deprecation — in-app banner with sunset date, alternative path, migration guide link. Removes the "surprise removal" failure mode that erodes user trust. Modeled after MongoDB LeafyGreen end-of-life pattern.

When this pattern applies

Primary triggers

Mark a feature for end-of-life in a Koder product

All triggers

Deprecate or remove a feature in a Koder product
Plan a breaking-change release (token rename, API change)

Pattern — Deprecation

Status: v0.1.0 — Draft. Mandatory pattern; every deprecation in a Koder product MUST follow it. Ratified ahead of the first real deprecation hitting prod to avoid setting a worse precedent.

R1 — Announcement window

Feature tier	Min notice before removal
Free / community features	30 days
Paid / contracted features	90 days
Foundational / API-surface	180 days

Window starts the day the in-app banner ships (R3) — not the day the team decided internally.

In-app banner (using specs/components/banners.kmd warning severity):

Heading: Feature name will be removed on YYYY-MM-DD.
Body: 1–2 sentences explaining why + what replaces it.
Primary link: Migration guide → product docs.
Secondary link: Why this change → blog post or RFC.
Dismiss (×) per banner spec; reappears next session until removal date — 7d before removal, undismissable.

R3 — Copy template (en-US)

{Feature name} will be removed on {YYYY-MM-DD}.

{One sentence reason}. We recommend switching to {alternative} —
see the [migration guide]({migration_url}) for step-by-step instructions.

[Migration guide]  [Why this change]

Translatable per specs/i18n/contract.kmd. Keys deprecation.{slug}.heading|body|primary|secondary.

R4 — Migration guide contract

Every deprecation MUST publish a migration guide before banner ships:

Section 1: What changes
Section 2: Step-by-step migration (with code samples / screenshots)
Section 3: Timeline (today / 30d / removal date)
Section 4: Questions → support contact

Lives in the product's docs site (not KDS), URL stable through removal date.

R5 — Telemetry hook

Product SHOULD instrument:

Daily count of users still using the deprecated feature.
Click-through rate on migration-guide link.
Dismissal rate of the banner (informational; banner re-shows next session anyway).

Use the trend to confirm migration is on track before removal day.

R6 — Removal commit convention

The PR that removes the deprecated code MUST:

Reference the deprecation ticket: deprecate: remove {feature} per {ticket}.
Include a CHANGELOG entry under "Removed" section.
Land on a release commit (per policies/releases.kmd), never mid-cycle.

R7 — Frontmatter

Deprecation tickets carry deprecation: frontmatter:

deprecation:
  feature: feature-slug
  announce: 2026-06-01
  sunset:   2026-09-01
  replacement: new-feature-slug
  migration_url: https://product.koder.dev/docs/migration/feature-slug/

CI can lint that announce ≥ today + R1 window and sunset = announce + window.

Não-escopo

API-versioning policy (separate policies/api-versioning.kmd).
Refund / compensation rules for paid feature removals (legal / product owner decision).
Migration of user data (per-feature, not KDS-level).

References

specs/components/banners.kmd
policies/backlog.kmd
policies/releases.kmd