# Breaking changes and deprecation

Source: https://opvs.ai/docs/guides/vendors/breaking-changes

> What counts as a breaking change, how to ship a new major without stranding anyone, and how to retire a method gently.

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

Change

Bump

a new method

minor

a new optional parameter or entitlement

minor

better guidance or descriptions

minor or patch

fixing a wrong default

patch

docs, changelog, typo

patch

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](https://opvs.ai/docs/guides/vendors/versions-and-tiers.md#how-workspaces-receive-new-versions)). 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](https://opvs.ai/docs/guides/vendors/promote.md).