Release notes practice

How to sunset a feature without surprising customers

7 min read

To sunset a feature, find out who still uses it, decide what replaces it and on which date it goes, and tell those users early in the places they already look: the changelog, an email, the feature’s docs page and a notice inside the feature itself. On the announced date, remove it, publish a “Removed” entry and keep a path open for anyone who arrives late. Much of the risk sits in the notice period, because a removal nobody heard about lands as a bug report.

StageWhenWhat you doWhere users see it
DecideBefore any announcementMeasure usage, name the replacement, set the dateInternal only
AnnounceDay 1 of the notice periodPublish a “Deprecated” entry, email the feature’s recent usersChangelog, email, docs
Warn in placeThrough the notice periodShow a notice inside the feature with the dateThe feature itself
RemindShortly before the dateEmail the users who still rely on itEmail, in-app notice
RemoveThe announced dateSwitch it off, redirect old links, publish a “Removed” entryChangelog, release notes
Follow upWeeks afterAnswer stragglers, keep redirects and data rulesSupport, redirects

What does it mean to sunset a feature?

It means retiring a product feature on a planned date, after telling the people who use it what is changing and what to use instead. A sunset has three parts: the announcement, a notice period in which the feature still works, and the removal itself.

The terms for the stages of a sunset overlap in practice. “Deprecated” usually describes the notice period, when the feature still works but is going away, and “removed” describes the end state. Keep a Changelog uses exactly that split, with “Deprecated for soon-to-be removed features” and “Removed for now removed features.” For endpoints that other software calls, the same process has its own conventions, covered in API deprecation.

How do you decide which feature to sunset?

Start from who uses the feature and what they use it for; what it costs to keep comes second. A feature with few users can still be the reason a large customer stays, and a busy one can be served better by its replacement.

The UK government’s Service Manual puts this well for whole services: “When retiring a service you should consider user needs in the same way you did when you built the service.” It asks teams to work out what happens to each need: it may no longer exist, something new may meet it, or someone else may. The same three outcomes apply to a single feature.

Usage data narrows the list. Look at how many accounts touched the feature recently, which plans they are on and whether the usage is repeated or a single try. Feature adoption covers how to measure that without counting one-off visits as use. Then talk to a few of the heaviest users before the decision is final, since they will tell you what the replacement is missing.

How much notice should you give before removing a feature?

Enough for users to finish the work you are asking of them, which depends on what they have to do. Switching to a replacement button takes minutes, while moving data or rewriting an integration can take months.

Large vendors publish their minimums, and they are a useful reference. Microsoft’s Modern Lifecycle Policy promises “a minimum 30 days’ notification when customers are required to take action in order to avoid significant degradation,” and “a minimum of 12 months’ notification prior to ending support if no successor product or service is offered.” Google Cloud’s terms commit to notifying customers “at least 12 months before” discontinuing a service or associated material functionality, unless Google replaces it with “a materially similar Service or functionality.”

The pattern in both is useful for a smaller product too: a short period when a replacement exists and the move is small, a long one when users must find a new home for the work. If your contracts or terms promise a notice period, that number is the floor, so check it before announcing a date.

What should a feature sunset announcement say?

What is going away, on which date, why, what to use instead and what happens to the user’s data. Readers should be able to act on the announcement without opening a support ticket.

A short example of an entry for the start of the notice period:

### Deprecated: Saved views (removal on 2 March 2027)
Saved views will be removed on 2 March 2027. Filters on
the dashboard now cover the same need and are shared
across your team. Until then, saved views work as before.
To move: open each view and choose "Save as filter".
Views you have not moved by 2 March will be exported to
CSV and emailed to the account owner.

Each line answers a question someone would otherwise ask support. The exact date matters more than the reason, and the migration step matters more than both. If the replacement behaves differently, say how, because heavy users will compare the two. Avoid “in the coming months”: a vague date is one nobody plans around.

Where should you announce a feature removal?

Everywhere the affected users might look, with the most direct channel aimed at the people who actually use the feature. A changelog entry reaches people who read changelogs, and the person who uses the feature every Tuesday may not be one of them.

Use four channels together:

  1. The changelog, as the dated public record that support and sales can link to.
  2. Email to recent users of the feature, from your usage data, with the date in the subject line, and a reminder shortly before the date to those still using it.
  3. A notice inside the feature, shown every time it is opened, with the date and a link to the migration steps.
  4. The docs page for the feature, marked as deprecated with the same date.

The in-feature notice does the most work, because it reaches exactly the right people at the moment they rely on the feature. Changeloop’s widget shows the changelog inside your product, so the deprecation entry is visible to users without leaving the app. Picking channels for announcements in general is covered in new feature announcement, and the email itself follows the same rules as a product update email.

What happens on the day you remove the feature?

You switch the feature off on the announced date, publish a “Removed” entry that links back to the deprecation notice, and keep a way through for anyone who arrives late. Moving the date at the last minute teaches users that your dates are suggestions.

The old entry points need care. Links, bookmarks and help articles that pointed at the feature should lead somewhere useful, like the replacement or a page that explains the removal. For a service that was live longer than six months, the Service Manual requires the old address to keep redirecting “for a year after the time it retired or until the current SSL certificate expires, whichever comes first.” Data needs a plan too: the same guidance says to keep the retention policies you already have and to tell users when their data moves.

In Changeloop, unless auto-publish is on for the repository, the pull request that removes the feature lands in the review inbox described in the docs: as a draft to approve or, if it is judged not user-facing, as a discarded item you can restore. Before approving, add the date of the original notice and the replacement, which the code change alone does not describe.

Expect a few late reactions. Brief support with the announcement, the replacement and the export path before the date, and if requests to keep the feature arrive, answer them the way you would any declined request: declining feature requests covers how.

FAQ

What is the difference between deprecating and sunsetting a feature? Deprecating announces that a feature will be removed while it keeps working, and sunsetting is the whole planned retirement, from that announcement to the removal date. Many teams use the words interchangeably, so state the removal date in either case.

Do you need to announce removing a feature nobody uses? Yes, briefly. Usage data can miss some paths into a feature, and a one-line “Removed” entry in the changelog costs little and saves the one remaining user from reporting the removal as a bug.

Can you sunset a feature that customers pay for? Yes, but read your terms and contracts first, because they may promise a notice period or a refund. Give paying customers the longest notice you can, a replacement or an export, and a direct contact for questions.

What if customers push back on the removal? Listen for what the replacement is missing, since that is usually what the pushback is about, and fix the gap if it is real. Keep the date unless you learn something that changes the decision, and if you do move it, announce the new date the same way as the first.


The technical claims in this article have not been independently reviewed. If something here is wrong, tell us and we will correct it.

Related on Changeloop: /docs/widget, Developer docs

changeloop
The team building a closed-loop changelog. Your users ask, your team ships, the person who asked gets told.