---
title: "Release a breaking change"
description: "Approve an intentional contract break at the source, set each affected Target's version, and merge the exact destination candidate."
url: https://typeship.dev/docs/guides/release-a-breaking-change
markdown: https://typeship.dev/docs/guides/release-a-breaking-change.md
section: "Get started"
---
> ## Documentation index
> Fetch the complete documentation index at https://typeship.dev/llms.txt (every page, one line each) or the full text at https://typeship.dev/llms-full.txt.
> Append .md to any docs URL, or send Accept: text/markdown, for the markdown twin of that page.

# Release a breaking change

Approve an intentional contract break at the source, set each affected Target's version, and merge the exact destination candidate.

A source pull request and a destination pull request make different decisions. The source review decides whether the API change is intentional. Each destination review decides whether one exact generated package is ready to release.

1. **Review the source change**
   
   Open the sticky Typeship report on the Definition pull request. Check the objective breaking changes, Diagnostics, affected methods, and every Target's preview result.
   
   If the change is accidental, fix the Definition and push again. If it is intentional, apply the repository's `typeship:breaking-approved` label. The label records approval; it does not rewrite the objective result as compatible.
   
   Do not change package versions in the source pull request. Several Definition changes may accumulate before a Target releases, and different Targets may release on different schedules.

2. **Merge the Definition**
   
   After the source checks pass, merge the Definition change. Automatic generation opens or updates one destination candidate per changed Target. Every candidate compares against the last `.typeship/surface.json` actually merged in that destination, not against the last source pull request or an abandoned candidate.
   
   A Project with a URL source starts here because it has no source pull-request preview.

3. **Set each Target's next version**
   
   Open the destination pull request. `Typeship – release readiness` names the minimum version required by the complete unreleased diff:
   
   | Change delivered by this Target                | Minimum SemVer change          |
   | ---------------------------------------------- | ------------------------------ |
   | Breaking API or package contract               | Major, or minor before `1.0.0` |
   | Compatible consumer functionality              | Minor                          |
   | Documentation or generator implementation only | Patch                          |
   
   Set `proposed_version` independently on each affected Target, then regenerate:
   
   ```bash
   typeship targets retrieve tgt_...
   typeship targets update tgt_... --proposed-version 0.7.0
   typeship projects generate prj_...
   ```
   
   A larger intentional version or valid prerelease is allowed. Versions cannot move backward. OpenAPI `info.version` and GraphQL schema metadata do not set package versions.

4. **Merge the candidate**
   
   Require `Typeship – release readiness` in each destination repository. Merge only while it is green. A human commit on the bot-owned branch changes the candidate and fails readiness; move repository-owned CI or release configuration to the default branch, then regenerate.
   
   Merging the exact candidate advances `current_version` and creates one immutable `rel_*` Target Release. Closing the pull request, merging a source pull request, or publishing an unreviewed local package does not.
   
   ```bash
   typeship targets list-releases tgt_...
   ```
   
   Your destination repository's release workflow can then publish the reviewed version to npm, PyPI, or as a Go tag. Typeship does not receive registry credentials.

## Multiple Targets

Treat each Target independently. A breaking response change may affect every CLI, MCP, and SDK Target, while a package-only export change may affect one. Set and merge only the versions required by each destination's cumulative report.

> **For AI agents:** Do not infer a version from the source pull request. Read `api_compatibility`, `package_compatibility`, `version_correct`, and `release_readiness` from the destination Generation. Set `proposed_version` on that `target_id`, and never merge or publish without user authorization.

## Sitemap

[Every page of these docs](https://typeship.dev/llms.txt)