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 the gen.lock file differs from the version field in the gen.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 the gen.yaml file.

Via the Dashboard

To manually set a version for your SDK in the Speakeasy dashboard:

  1. Navigate to the Publishing tab of your SDK and select "Set a New Version."
https://app.speakeasy.com/org/

Screenshot of the publishing tab in the Speakeasy dashboard.

  1. Enter your version following SemVer conventions. The dashboard validates the version and ensures it does not override a previously published version.
https://app.speakeasy.com/org/

Screenshot of the version pop-up in the Speakeasy dashboard.

  1. When you are ready, click "Submit Version Change."