Breaking changes and deprecation

A change is breaking when an agent that worked with your old version would fail with the new one. That needs a major version.

What is breaking

• Removing a method, or renaming a method or a required parameter.

• Changing a reply shape an agent reads (a field that moves, changes type or disappears).

• Adding a new required input to an existing method.

• Changing a required entitlement.

• Changing a credential: a renamed variable, a different auth_type, or an optional credential becoming required.

What is not

The test: could an agent that worked yesterday break tomorrow because of this change alone? If yes, it is a major.

Ship a major safely

Remember that workspaces on latest receive new versions automatically (Versions and trust tiers). A major reaches them too. So:

1. In the last minor of 1.x, add the new surface beside the old one,
   and mark the old one deprecated (see below).
2. Give workspaces time to move: weeks, or a quarter.
3. Publish 2.0.0 with the old surface removed. Its CHANGELOG is the upgrade guide:
   what was removed or renamed, the new shape, the least a workspace must do.
4. Leave 1.x published. Workspaces pinned to ^1 or an exact 1.x keep running it.
5. Revoke 1.x only if it is unsafe.

Deprecating without breaking

There is no platform "deprecated" flag today: a version is published or revoked. Deprecation is a convention:

1. Publish the replacement (a new method, or a new version).

2. Mark the old one as superseded where agents and people will see it:

• in the old method's guidance.warn, for example "Do NOT use findLeads for new work; use searchLeads." Agents see this on every call, which makes it the strongest signal you have;

• a CHANGELOG.md entry: "findLeads is deprecated; it will be removed in 2.0.0";

• the long description on your detail page.

1. Leave the old one working.

Example

1.5.0 (minor)  add searchLeads beside findLeads
               findLeads guidance.warn: "Do NOT use findLeads for new work — use searchLeads."
               CHANGELOG: "findLeads is deprecated; migrate before 2.0.0."
        ── grace period ──
2.0.0 (major)  remove findLeads

When a peer ships a major

If you depend on a peer with ^1.0.0 and it ships 2.0.0, your range keeps you on 1.x. Test against the new major, then publish a version of your package with the range moved to ^2.0.0.

Next

Promote your package.