## TL;DR
Deprecation announcements need four things: what is going away and when, why (one honest sentence), the migration path with docs, and what happens on shutdown day to anyone still using it. Announce early, repeat often, and give humans a way to reach you. Customers forgive removals; they do not forgive surprises.

## The query

```text
how to tell customers a feature is deprecated
```

## Use this when

- Planning a feature deprecation
- Writing the deprecation announcement
- Handling support fallout from a removal
- Building the deprecation communication plan

## Not for

- Pricing or plan changes
- Security vulnerability disclosures
- Internal-only sunsetting docs
- Unannounced removals (do not do those)

## Steps

### 1. Announce early with a real timeline

Minimum 90 days for paid features, longer for anything customers built on. "Deprecated effective [date], removed on [date]." Two dates, not one: deprecation (no new use, still works) and removal (gone).

Expected output: two published dates.

### 2. Give one honest reason

"We are consolidating on [new approach]" or "Usage dropped below sustainable levels." One sentence. Customers can tell when the reason is evasive, and evasiveness breeds conspiracy theories.

Expected output: a one-sentence reason.

### 3. Provide the migration path, not just the news

Step-by-step migration docs, ideally with a tool or script. The announcement should link the guide, not describe it. Every deprecation ticket is really asking "what do I do now" - answer it before they ask.

Expected output: a migration guide linked from the announcement.

### 4. Say what happens on shutdown day

Accounts still using the feature get what: an automatic migration, a read-only archive, or a hard stop. Write it down. "We will figure it out" is how shutdown day becomes a support catastrophe.

Expected output: a written shutdown-day behavior.

### 5. Repeat the message in every channel

In-app banner, email, docs, changelog, and support macros. Customers do not read announcements; they encounter them. The support team needs macros ready before the first confused ticket arrives.

Expected output: the message live in all channels plus support macros.

## Template: the announcement

```text
Subject: [Feature] is being retired on [removal date]

What is changing: [feature] is deprecated as of [date] and will be removed on [removal date].
Why: [one honest sentence].
What to do: migrate to [replacement] using this guide: [link]. Most customers finish in [time].
On [removal date]: [what happens to remaining usage - auto-migrated / archived / stopped].
Questions: reply here or talk to support. We will help with the migration.

Timeline: deprecated [date] -> reminders [dates] -> removed [date].
```

## Variant phrasings

### feature deprecation email

Steps 1 through 4 plus the template.

### sunsetting a feature announcement

Full sequence. Step 5 is where announcements succeed or fail.

### how to retire a feature without angering users

Steps 2, 3, and 5. Honest reason, migration path, repetition.

## Why it works

Deprecation anger is almost never about the feature. It is about surprise, missing migration paths, and shutdown-day ambiguity. The four-part announcement plus multi-channel repetition removes all three. Early announcement also surfaces the heavy users you did not know about, while there is still time to help them.

## Edge cases

- Enterprise contracts referencing the feature: legal review first. Contractual commitments beat roadmaps.
- The feature has no replacement: say so and say what you recommend instead. Do not pretend.
- Heavy API users: give them longer timelines and direct outreach. API deprecations break code, not just workflows.
- The deprecation gets reversed: announce the reversal as loudly as the deprecation. Trust compounds.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_6AVagn1kdb3eyly791CBVA