Skip to main content
Orvianlaunch home

This week is in orbit

Compatibility and Deprecation Notices: Warn Users Early

Integrations · 10 min read ·

Connections change. How to announce deprecations, version changes and end-of-life for integrations in time, in plain words, with a clear path forward.

Illustration: A timeline across the page in midnight navy: Announce, Warn, Sunset, Remove, with ring markers and short labels under each and a sliding bar for notice period

Every connection has a lifespan. An interface is replaced by a newer one. A platform changes how it handles sign-in. A partner closes. A feature that seemed essential a year ago is now used by a handful of people and costs more to maintain than it is worth. Retiring things is part of running any product that connects to others.

The way you do it determines how users remember you. A change announced early, in plain words, with a clear path to something that works is an inconvenience. The same change discovered when an automation silently stops is an injury. This guide covers how to manage compatibility and deprecation so that users are told before it breaks.

The vocabulary

Deprecation is the discouragement of use of a feature, practice or interface, usually because it has been superseded, while it remains available for now. A deprecated item still works; it is on notice.

Backward compatibility is the property of a system that allows newer versions to work with inputs, data or connections designed for earlier ones. A system that is backward compatible lets users upgrade without rewriting what they have built.

Versioning is the practice of labelling releases so that users can tell what has changed. Semantic versioning, for example, uses a three-part number whose parts signal the size and kind of change: a change that breaks compatibility, one that adds features without breaking, and one that fixes problems.

Sunset is the date on which a deprecated item stops working. End of life is the point at which support ends altogether.

Use these terms consistently, and explain them where your readers might not know them.

Why careful notice matters

Integrations sit inside other people's work. A user may have built a workflow, a spreadsheet, a report or a process around a connection and not looked at it for months. When it breaks, they discover it from the effect: missing records, failed tasks, confused colleagues.

The costs are high for them, and for you. Support tickets spike, trust drops and some users leave. For developers who have built on your open interface, a breaking change without notice can damage their own customers, and they will remember.

Good practice has a simple basis: those who depend on you should never be surprised.

Decide what is changing

Before you write a notice, be clear on the nature of the change.

  • Additive change: new features or fields that do not affect existing use. Usually needs no warning, but can be mentioned in the changelog.
  • Behaviour change: something works differently, though not removed. Warn, because it can break assumptions.
  • Deprecation: something is on notice. Announce and set a timeline.
  • Removal: something stops working. Give the date and the alternative.
  • Security-driven change: may need to be faster. Explain why.
  • Change imposed by a partner: you may have little time yourself. Pass on what you know as soon as you know it.

Where you can, prefer backward-compatible changes. Keeping old behaviour working while offering new, and retiring the old only when necessary, is kinder than forcing change.

How much notice

There is no universal answer, but principles help.

  • Match notice to dependency. For something a few people use casually, weeks may be fine. For an interface that products are built on, many months is typical.
  • Consider the effort to migrate. The harder the move, the longer the notice.
  • Consider who is affected. Developers need time to plan, test and release. Individual users may need less.
  • State exceptions: for urgent security issues, you may need to act fast, and should explain.
  • Publish your policy in advance, so that users know what to expect: for example, a minimum notice period for breaking changes to the open interface.

Stick to the periods you promise. If you must shorten them, say why and help affected users.

What a notice contains

A good notice is short, specific and actionable. Include:

  1. A headline that says what is changing and who is affected.
  2. What is changing, in one or two sentences.
  3. Why, briefly and honestly.
  4. Dates: announcement, any warning stage, the sunset date and the end of support. State time zones if times matter.
  5. Who is affected, and how to tell if you are. For developers, how to check usage.
  6. What will happen if they do nothing: for example, requests will return an error.
  7. What to do instead: the replacement, with a link to a migration guide.
  8. How to get help: a contact, a forum or an office-hours session.
  9. What is not changing, to reduce anxiety.
  10. A way to ask for more time, in genuine hardship, if you can offer it.

Avoid euphemism. "We are streamlining our offering" hides the fact that something is being removed. Say it plainly.

A migration guide

For anything that requires user action, a migration guide is as important as the notice.

  • Describe the old and the new side by side.
  • Give step-by-step instructions, with examples.
  • Show before-and-after code or settings, where relevant.
  • List common problems and fixes.
  • Offer a way to test the new path before the old is removed.
  • Say how long it takes, realistically.
  • Provide a tool or script for the migration if you can.
  • Keep the guide in your documentation, linked from the notice.

If you cannot give a clear path forward, think again about whether to make the change.

Channels

People miss single notices. Use several channels, matched to the audience.

  • In the product, a message where affected users will see it.
  • Email to affected users, targeted by actual usage, not to everyone.
  • The changelog, dated and permanent.
  • The documentation, with a visible note on the affected pages.
  • The status page, for changes with a date.
  • The developer mailing list or forum, for those who built on the open interface.
  • Response headers or warnings in the interface itself, so that automated callers can detect upcoming changes, where your design allows it.
  • The integrations page, with the status marker updated.

Repeat the message at intervals: at announcement, at the halfway point, a month before, a week before and a day before. Each reminder should say how many days remain.

Handling stragglers

Some users will not act in time. Plan for it.

  • Identify them, from usage data.
  • Contact them personally in the last weeks.
  • Offer help, not blame.
  • Consider a grace period or a brown-out, a short test period in which the old behaviour is temporarily disabled to reveal who is still using it. If you do, announce it clearly in advance.
  • Be firm on the final date, except in cases of real hardship, or the date means nothing.
  • Keep a record of notices sent.

When a partner changes

Sometimes the change comes from outside. A platform you integrate with announces a new version or a shutdown.

  • Tell your users as soon as you know, even before you have a plan. "We have heard that X will change on this date. We are assessing and will update by this date."
  • Assess the impact: who is affected, what will break.
  • Decide: adapt, replace or retire your integration.
  • Communicate the decision, with a timeline.
  • Update the listing and status marker the moment something is known.
  • Follow the partner's notices, and subscribe to their developer updates. The guide on choosing ecosystem partners recommends agreeing on how changes will be shared.

Retiring an integration

If you are the one ending a connection:

  • Explain why: low usage, unsustainable maintenance, the other party's change.
  • Give alternatives: another integration, the open interface, an export.
  • Provide a way to take data out.
  • Keep a page at the same address that says the integration has been retired, with the date and the alternatives, rather than deleting it.
  • Thank the users and, where relevant, the partner.

Making it routine

The best deprecation processes are boring.

  • Publish a policy on versioning, notice and support.
  • Keep a deprecation register, a list of items on notice, with dates and owners.
  • Review the register monthly, and send reminders on schedule.
  • Test the new path before announcing.
  • Monitor usage of deprecated items to see who still depends on them.
  • Write notices from a template, to ensure all the key information appears.
  • Learn from each one: what questions came back, what was unclear.

A worked example

A small company offers an open interface used by a few dozen developers. Version one has a clumsy way of listing records, and a security review shows a weakness in its authentication method. The team builds version two, with a better design, and decides to retire version one.

They publish a notice: "Version one of the interface will stop working on 1 October. Version two is available now." It states why, links to a migration guide with before-and-after examples and offers a test environment. They set up usage reports and email the thirty-one developers who made calls in the past ninety days. They add a warning header to version one's responses, mention it in the documentation and changelog and post to the developer forum.

At the halfway point, they email again with the number of days left, and personally contact the nine developers who have not yet moved. Two ask for more time, and the team agrees to a short extension for one with a genuine constraint. A week before, they run a ten-minute brown-out and find that three more users were still calling the old version; they contact them and help. On 1 October, the old version stops, with one call in the last day. Support receives five questions, all answered in a day. The notice was dull. It was also why nothing broke.

Questions makers ask

Is it better never to remove anything? That is costly. Old versions burden maintenance and security. Retire with care.

What if almost nobody uses it? Still notify them. Small numbers can still be important customers.

Can I deprecate silently and remove later? No. A deprecation that nobody knows about is a surprise removal.

How do I handle changes in a hurry? Be honest about why, give what notice you can, and help.

Summary

Connections have lifespans, and the way you retire them shapes trust. Know the difference between additive, behavioural, deprecating and removing changes, prefer backward-compatible ones and publish a notice policy. Each notice should say what, why, when, who, what to do and where to get help, and be backed by a migration guide and a test path. Use several channels, repeat at intervals, help stragglers and keep records. Pass on partners' changes as soon as you hear. Users should never be surprised by something that you knew was coming.

Questions and answers

What is deprecation?
Marking a feature, version or interface as outdated and due to be removed in the future, so that users have time to move.
How much notice should I give?
Enough for users to adapt. For interfaces others build on, many months is common, and shorter only for urgent security reasons.
What should a deprecation notice include?
What is changing, why, the dates, who is affected, what to do instead and where to get help.
How do I tell users?
Through several channels: in the product, by email to affected users, on a changelog and status page and in documentation.
What is backward compatibility?
The property that newer versions continue to work with things built for older versions.

Sources

Related guides

Ask a question