中文
devexamples
← Workflows

阅读中文版本

Breaking Change Deprecation Workflow

Classify a change as breaking, offer a compatible path during a transition, communicate a timeline, and remove the old behavior only after migration.

intermediate~120 minapiversioningcommunication

Objective

Ship a breaking change through a controlled transition so consumers can migrate without an outage.

Environment

  • A versioning and deprecation mechanism
  • Consumer communication channels

Steps

1. Classify the change and identify affected

Classify the change and identify affected consumers.

Expected state: The impact is known.

2. Provide a compatible path: a new

Provide a compatible path: a new field, endpoint, or opt-in.

Expected state: Consumers can migrate before removal.

3. Announce the timeline and monitor usage

Announce the timeline and monitor usage of the old path.

Expected state: You can see migration progress.

4. Remove the old behavior once usage

Remove the old behavior once usage is zero or the deadline passes.

Expected state: Removal is deliberate.

Decision points

Hard cut or transition period?

  • Transition period
  • Hard cut

A transition period with telemetry; a hard cut only for unused or internal paths.

Remove on schedule or when idle?

  • When usage is zero
  • On schedule

Prefer zero usage; schedule is a fallback with explicit consumer acknowledgement.

Expected outcome

Consumers migrated to the new behavior with the old path removed on a communicated timeline.

Verification

Confirm old-path usage dropped to zero before removal and that migration documentation was published and used.

Cleanup

Archive the deprecation notice and update the changelog.

Overview

Ship a breaking change through a controlled transition so consumers can migrate without an outage. Confirm old-path usage dropped to zero before removal and that migration documentation was published and used.

Steps

  1. Classify the change and identify affected consumers. Expected state: The impact is known.
  2. Provide a compatible path: a new field, endpoint, or opt-in. Expected state: Consumers can migrate before removal.
  3. Announce the timeline and monitor usage of the old path. Expected state: You can see migration progress.
  4. Remove the old behavior once usage is zero or the deadline passes. Expected state: Removal is deliberate.
// transitional: support both shapes
const quantity = req.body.quantity ?? req.body.qty;
// log usage of the deprecated field for migration tracking

Verification

  • Consumers migrated to the new behavior with the old path removed on a communicated timeline.

Decision points

  • Hard cut or transition period? Options: Transition period; Hard cut. Recommended: A transition period with telemetry; a hard cut only for unused or internal paths.
  • Remove on schedule or when idle? Options: When usage is zero; On schedule. Recommended: Prefer zero usage; schedule is a fallback with explicit consumer acknowledgement.