DocumentationExamplesGuides

SDK Versioning

Speakeasy SDKs are automatically versioned using Semantic Versioning Semver (opens in a new tab). This means each new generation will bump the version of the SDK.

The logic for versioning is as follows:

  • Speakeasy when we release new changes to the generator we version these changes against features of an SDK, if your SDK uses any of these features then the SDKs version will be bumped along with the features version.
  • When you release changes to your OpenAPI document and the info.version of the document is Semver compliant, we will bump the SDK version (ie bump Minor by one if the Minor version of your document changes) along with the bumps in the version, otherwise we will bump the Patch version if the checksum has changed.
    • Coming Soon We will detect the type of changes to your document such as adding a breaking change to parameters of operation and bump versions accordingly.
  • If your gen.yaml changes we will bump the Patch version of the SDK.

Major Version Bumps

For new SDKs versioning will generally start at 0.0.1 and be bumped from there.

But we won't automatically bump the Major version of a SDK if it is below 1.0.0. Once it has been manually bumped to 1.0.0 we will then automatically bump the Major version for breaking changes. (Except in the case of Golang SDKs see Golang Major version bumps)

Golang Major version bumps

When bumping the Major version of a Golang module past v1, the import path must change to include the major version. For example, if the module is currently at v1.2.3, the import path is github.com/speakeasy/speakeasy-go. When bumping to v2.0.0, the import path must change to github.com/speakeasy/speakeasy-go/v2.

Therefore Major version bumps for Golang SDKs need to be considered carefully as they have an outsized impact on the migration path for users. There bumping the Major version is left to the discretion of the SDK maintainer.

Manually bumping the version

Speakeasy supports manual control of the version of the SDK. This can be done by setting the version field in the gen.yaml file. This will override the automatic versioning logic for the next generation.

We detect you have manually set the version by checking if the releaseVersion field in the gen.lock file against the version field in the gen.yaml file. If they are different we will not automatically bump the version.

Once they match again we will resume automatic versioning.

We also have a CLI Bump Command that can be used to help bump the version (or set a specific version) of the SDK, without needing to manually edit the gen.yaml file.