Once you’ve identified a change as breaking (see Versioning and breaking changes), follow these steps to ship it without breaking the consumers who depend on it.

Warning

Before changing an output port, open the product’s Consumed by view to see which products depend on it. A change that looks local is only local if nothing downstream reads that port.

  1. Identify who is affected. Check the consumers of the port you are changing, and the lineage beyond them.
  2. Decide whether to version or to add. If consumers can migrate quickly, raise the port’s MAJOR version. If they cannot, add a new output port alongside the existing one and run both.
  3. Announce it before you ship it. Tell the affected owners what changes, when, and what they need to do. The product’s version notes are the durable record.
  4. Update the contract. Revise the data contract covering the port so its schema and terms match the new reality, and have the Steward approve it.
  5. Give consumers a migration window. Keep the old interface working long enough for them to move, based on what they told you in step 1.
  6. Retire the old interface. Remove the superseded port or version once the consumers you identified have migrated.

Running two interfaces at once costs more than a clean cut, which is why step 2 is a judgment call rather than a rule. The cost of a clean cut lands on other teams; the cost of running both lands on you.