Skip to content

Update deprecation and removal content guidelines

Problem

Right now, we're often treating deprecations like notifications of an incoming removal. But users see a deprecation as a warning that you need to take action, to prevent a breaking change in the future. It's a subtle difference, but important. When they see a deprecation announcement, they expect to be able to do something immediately.

(Original source)

Proposed solution

We should make it a requirement that all deprecations are actionable. This list of Stripe's API changes shows the kind of implementation we should strive for.

Key terms to take note of: deprecated in favor of, removed in favor of, use YYY instead, etc. It is clearly explained what people need to do for each item.

Examples:

  • We have removed tax_percent from objects and requests in favor of tax rates.
  • Deprecate the payment_method.card_automatically_updated webhook in favor of payment_method.automatically_updated.
  • Checkout Sessions no longer include the display_items property. Use the includable line_items property instead.

Then our requirement that breaking changes be announced at least 2-3 milestones before the major milestone means:

  • We're not giving users 2-3 milestones to prepare for the change. We're giving them time to make the change.
  • It isn't good enough to just make an announcement, we must have the deprecation action available at least 2-3 milestones before the breaking change as well. In fact, the deprecation process could be essentially: "Step 1, prepare the replacement, step 2, create the deprecation, Step 3..."

What is the Action when a replacement isn't provided?

The action would be "Discontinue use of this feature by X.Y."

An example that we should try to avoid would be:

  • Deprecation: Feature A is being removed, to be replaced with a future feature. Action: Wait for the future feature, and switch to it when it becomes available.

In this case, the deprecation should be delayed until the replacement is available.

How to do it

Edited by Brian Rhea