Release a breaking change
Approve an intentional contract break at the source, set each affected Target's version, and merge the checked Draft.
Release an intentional API break by approving the source change, reviewing each affected Target's version, and merging its checked Draft. You need a saved Project and write access to the source and destination repositories.
Source approval records the API decision. The destination review checks the package and version your users will receive. If automatic generation is off, request Generate now after the source changes.
Review the source change
Open the sticky Typeship report on the Spec pull request. Check the objective breaking changes, Diagnostics, affected methods, and every Target's preview result.
If the change is accidental, fix the Spec 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 Spec changes may accumulate before a release, and different Targets may release on different schedules.
Merge the Spec
After the source checks pass, merge the Spec change. Automatic generation opens or updates one Draft per changed Target. Compatibility is compared with the latest release, regardless of registry publishing status. A closed or abandoned Draft does not become a release.
A Project with a URL source starts here because it has no source pull-request preview.
Confirm each Target's next version
Open the destination pull request. Typeship Release names the minimum version required by the unreleased changes:
Every Target follows reviewed SemVer. Before 1.0.0, breaking changes require at least a minor version; this policy is fixed rather than a Target setting.
| 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 |
Typeship immediately selects that minimum from the cumulative Draft. Keep the automatic version, choose a larger version, or use a prerelease. You can select a version in the Console, through the Draft resource, or by editing the PR title to release: X.Y.Z:
typeship targets get tgt_...
typeship drafts update drf_... --version-next 0.7.0A larger intentional version or valid prerelease is allowed. Versions cannot move backward. OpenAPI info.version and GraphQL schema metadata do not set package versions.
Merge the Draft
Require Typeship Release and the Target's package checks in each destination repository. Merge only while both are green. A repository-writer commit on the Draft triggers a fresh merge and checks for that commit; a rewritten Draft recovers during Generate, while rewritten default history requires recovery approval.
Merging a checked Draft with package changes creates one immutable rel_* Release. Use release history and GET /targets/{target_id}/draft for release decisions. Closing the pull request, merging a source pull request, or publishing an unreviewed local package does not advance the latest release.
typeship releases list --target-id 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.
Do not infer a version from the source pull request. Read GET /drafts/{draft_id}, including its cumulative changes, compatibility, and version. Set version_next through PATCH /targets/{target_id}/draft, and never merge or publish without user authorization.