Deprecating features
Customers build integrations against our products and leave them running for years. Removing something they use (an endpoint, a parameter, a protocol, a URL) breaks those integrations, often in a place nobody at the customer remembers. A deprecation gives them the time and the signal to fix it before it breaks.
Example: plain HTTP on api.pro6pp.nl, pro6pp-api#2393.
Find out what breaks
Section titled “Find out what breaks”Read the production logs for who still uses the feature and how. Clients use URLs nobody remembers, such as spec files, WSDLs and sample downloads, so the logs set the scope, not the configuration.
Announce
Section titled “Announce”- Publish the timeline on the product’s deprecation page, such as the Pro6PP deprecation page: until when the feature works, each brownout, the cutoff, what fails and which URLs are affected.
- Mention upcoming deprecations and their brownouts in the customer newsletter.
Brownouts
Section titled “Brownouts”A brownout is a window before the cutoff in which the feature already behaves as it will after the cutoff. Integrations that still depend on it fail for a while, so their owners notice when there is still time to fix them.
- Make each brownout longer than the one before.
- Schedule them on working days within office hours (09:00 to 17:00), so customers are around to notice and act, and we are available to answer their support questions.
- Send each brownout as a calendar invitation to the colleagues who handle support and releases, so they know when to be around.
- Hardcode the windows and the cutoff in the configuration that serves the feature, so each one starts and ends by itself and nobody has to be around to switch it.
- Make sure nothing a brownout returns outlives its window. A temporary (302) redirect ends with the window; a permanent (301) one is cached by clients, which then keep following it.
- Test the schedule by setting the clock: run the real server at the start and the end of each window and at the cutoff.
Until the cutoff
Section titled “Until the cutoff”Keep a regression test that uses the feature the way customers do, so nothing removes it early by accident. During a brownout, the test expects the brownout behavior instead. After the cutoff, remove the feature, its exceptions and the schedule, and turn those tests into checks of the post-cutoff behavior.