SDK Versioning
Speakeasy-generated SDKs are automatically versioned using Semantic Versioning (SemVer (opens in a new tab)). With each new generation, the SDK version is bumped up.
Versioning Logic
The SDK version will be automatically incremented in the following cases.
Generator Version Changes
When Speakeasy releases a new generator version, it compares the features changed in the new generator to those used in your SDK:
- If multiple used features in your SDK change, the biggest version bump (major, minor, patch) across all the used features determines how the SDK version is bumped.
- If the features used in your SDK are unaffected by the new generator version, the SDK version remains unchanged.
Configuration Changes
- Changes to the
gen.yaml
file will bump the patch version. - Changes to the checksum will also bump the patch version.
OpenAPI Document Changes
- If the
info.version
section of your OpenAPI document is SemVer compliant, major or minor changes to the OpenAPI document will bump the major or minor version of SDKs correspondingly. - Coming Soon: Speakeasy will detect changes to the OpenAPI document (for example, adding a breaking change to the parameters of an operation) and bump versions accordingly.
Pre-release Version Bumps
Speakeasy supports any SemVer-compatible string as a valid version, including pre-release versions such as X.X.X-alpha
or X.X.X-alpha.X
.
- If your SDK is on a pre-release version, the Speakeasy automated version bumps will remain on the pre-release versioning until it is manually removed.
- Automated bumps will increment pre-release versions. For example,
1.0.0-alpha
,1.0.0-alpha.1
,1.0.0-alpha.2
. - To stop the pre-release versioning, manually set a new version or run
speakeasy bump graduate
.
Major Version Bumps
New SDKs start versioning at 0.0.1
and will be bumped from there. Speakeasy doesn't automatically bump major versions of SDKs with version numbers below 1.0.0
. When an SDK version number has been manually bumped to 1.0.0
, Speakeasy will automatically bump the major version for breaking changes.
Major version bumps to Golang SDKs impact the migration path for users.
Golang Major Version Bumps
When the major version of a Golang module is bumped past version 1
, the import path needs to change to include the major version. For example:
- Current version
1.2.3
:github.com/speakeasy/speakeasy-go
- Bumped to version
2.0.0
:github.com/speakeasy/speakeasy-go/v2
Carefully consider major version bumps for Golang SDKs because it significantly impacts the migration path for users. Major version bumping of Golang SDKs is left to the discretion of the SDK maintainer.
Manual Version Bumps
Speakeasy supports manual control of SDK versioning via the CLI and the dashboard.
Via the CLI
To override the automatic versioning logic for the next generation, set the version
field in the gen.yaml
file.
- The Speakeasy generator detects manual version settings when the
releaseVersion
field in thegen.lock
file differs from theversion
field in thegen.yaml
file. - Automatic versioning will resume when the version values in both files match.
- Use the Speakeasy CLI
bump
command to set the SDK version without manually editing thegen.yaml
file.
Via the Dashboard
To manually set a version for your SDK in the Speakeasy dashboard:
- Navigate to the Publishing tab of your SDK and select "Set a New Version."
- Enter your version following SemVer conventions. The dashboard validates the version and ensures it does not override a previously published version.
- When you are ready, click "Submit Version Change."