How-to › Release and secure packages

How to choose lockstep or independent versions across your SDKs#

Write one version rule for TypeScript, Python and Go SDKs into the compatibility policy, set it per target in sdkgen, and check the last three releases against it.

Audience
API producer
Level
intermediate
Topic
Version, changelog and automate releases
Languages
TypeScript, Python and Go
Verified

The Python wheel ships without py.typed, so mypy treats your SDK as untyped and skips its annotations. The fix is one line of Python packaging. Your TypeScript, Python and Go SDKs share one version number. So the release either tags TypeScript and Go with a patch that changes nothing in them, or tags Python alone and the three numbers stop matching.

What you get

You will end up with a version rule in your compatibility policy, an sdkgen overlay that follows it, and a check that your last three releases obey it. This is for you if you ship TypeScript, Python and Go SDKs from one API.

Short answer

Pick one of three rules and write it into the compatibility policy: lockstep, where every language shares MAJOR.MINOR.PATCH; minor-lockstep, where they share MAJOR.MINOR and each owns its PATCH; or independent versions. In sdkgen, set publish.version for each target in .sdk/model/project.aontu, run npx voxgig-sdkgen package update @voxgig/sdkgen --no-fetch, then npm run generate. Check the last three release tags against the rule with a script.

You will need

Node 22 or later, and an sdkgen project with ts, py and go targets, scaffolded as generate your first SDK with sdkgen shows. Releases tagged <lang>/vX.Y.Z, the form the release targets in sdkgen’s generated Makefile push, and a breaking-change verdict per language for each release, from whatever checker each language uses. The sample runs offline against files committed from one generation, listed in its README.md.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
Hand-maintained version tableA different generator per language, or a release every few monthsSomeone edits the table every release, because no check fails on a skipped rowYour tags already say everything the table would
oapi-codegenGo is the SDK, and its module is released with the service that owns itOne generated file and no go.mod, so every version decision is your module’s tagThe other languages need the same number from the same tool
ogenA Go client with typed optional fields and OpenTelemetry already wired inA generated package with no go.mod or version, so the rule lives outside the toolYou want one tool to stamp every language’s manifest
sdkgenOne model generates TypeScript, Python and Go into one repositoryA version key per target, a copy refresh before Go’s tag moves, and a hand-set /v2 pathEach language has its own repository and its own release owner
SpeakeasyIndependent versions, with the tool proposing each language’s bump on every generationAn account, and bumps read from info.version, a checksum and generator changes, not your surfaceStrict lockstep, because it turns detected Go majors into minors

Voxgig maintains sdkgen. It is one of the five rows in the table, and its own row says when to choose another.

The hand-kept table costs nothing to adopt, but no check fails when a row is skipped. Speakeasy computes a bump per language, which suits independent versions, but its bump reads info.version and a document checksum rather than the generated surface. ogen and oapi-codegen leave versioning wholly to the Go module you put their output in, which is the least machinery of the five and the least help.

Write the rule into the compatibility policy

The rule is a sentence a support engineer can quote and a field a script can read. Three rules are on offer. Lockstep gives one changelog and one support matrix, and forces a Go major when only the Python surface broke. Independent versions follow each language’s own changes, and leave “which Python goes with Go 1.9” to a lookup. Minor-lockstep sits between them, and answers the py.typed release, because Python takes a patch alone.1

{
  "rule": "minor-lockstep",
  "languages": ["ts", "py", "go"],
  "text": "Every language shares MAJOR.MINOR, which moves for every language when any language's surface gains or breaks something. PATCH belongs to each language and moves only for a fix in that language."
}

Put the text in the compatibility policy your users read, word for word. The other two fields are what check-releases.mjs enforces.

Set each target’s version in the project overlay

sdkgen keeps a release version per target, main.kit.target.<t>.publish.version, which defaults to 0.0.1. The overlay the scaffold writes gives the reason in a comment: “Per target, because ports publish to different registries on different clocks. Set every target to the same value for a lockstep repo”. The model language can do that in one line. Its spread, &:, applies one value to every child of a map, as the model reference lists, so one key sets all three targets.

# Lockstep: one line sets every target, through the model's spread, &:.
main: kit: target: &: publish: version: '1.4.0'

Inside .sdk/, refresh the project’s template copies, then generate. The refresh is what moves Go’s tag, as the section on failures shows.

npx voxgig-sdkgen package update @voxgig/sdkgen --no-fetch
npm run generate

versions.mjs reads the files that carry a version in two committed generations: the spread overlay in the preceding block, and an independent one with ts at 1.3.0, py at 1.3.1 and go at 2.0.0.

node versions.mjs generated/sdkgen/lockstep generated/sdkgen/independent
generated/sdkgen/lockstep
  ts  package.json   1.4.0  sdk reports 1.4.0  tag ts/v1.4.0
  py  pyproject.toml 1.4.0  sdk reports 1.4.0  tag py/v1.4.0
  go  VERSION        1.4.0  sdk reports 1.4.0  tag go/v1.4.0   module github.com/voxgig-sdk/bookshelf-sdk/go
  no problems
generated/sdkgen/independent
  ts  package.json   1.3.0  sdk reports 1.3.0  tag ts/v1.3.0
  py  pyproject.toml 1.3.1  sdk reports 1.3.1  tag py/v1.3.1
  go  VERSION        2.0.0  sdk reports 2.0.0  tag go/v2.0.0   module github.com/voxgig-sdk/bookshelf-sdk/go/v2
  no problems

Each version lands in three places: the manifest, the version the SDK reports from its config, and the tag its Makefile pushes. The Go tag starts go/ because the module sits in the go/ subdirectory, which is where Go looks for its tags. The independent overlay also sets main: kit: target: go: module: path: to end in /v2, because the Go modules reference requires that suffix from major version 2.2 sdkgen does not add it: without that line the module path stays .../go.

Check the last three releases against the rule

A rule nobody checks drifts on its first exception. releases.json holds three releases as tags plus each language’s verdict: a minor in every language, a TypeScript date fix, and the py.typed fix. Check them against strict lockstep first.

node check-releases.mjs policy-lockstep.json releases.json
policy-lockstep.json: lockstep over ts, py, go
  release 1  add published to Book                follows the rule
  release 2  ts: parse dates as UTC               breaks the rule
    py: no tag, the rule expects py/v1.4.1
    go: no tag, the rule expects go/v1.4.1
  release 3  py: ship py.typed in the wheel       breaks the rule
    ts: no tag, the rule expects ts/v1.4.2
    py: tagged py/v1.4.1, the rule expects py/v1.4.2
    go: no tag, the rule expects go/v1.4.2
  1 of 3 releases follow the rule

The same history under the rule in policy.json:

node check-releases.mjs policy.json releases.json
policy.json: minor-lockstep over ts, py, go
  release 1  add published to Book                follows the rule
  release 2  ts: parse dates as UTC               follows the rule
  release 3  py: ship py.typed in the wheel       follows the rule
  3 of 3 releases follow the rule

Strict lockstep asked for four tags with nothing in them. The TypeScript fix wanted Python and Go 1.4.1, and the Python fix wanted TypeScript and Go 1.4.2. Run the check in CI on every release tag; it exits 1 on a broken rule, which stops the publish job.

Carry the rule into the two Go-only generators

Both tools generate a Go package into a module you own, and leave its version to that module. go-tools.mjs reads what each wrote from the same api.json:

node go-tools.mjs
api.json info.version: 1.0.0
ogen
  8 .go file(s), package bookshelf, go.mod written: no
  info.version 1.0.0 in the code: no
  header: Code generated by ogen, DO NOT EDIT.
  modules it imports: github.com/go-faster/errors, github.com/go-faster/jx, github.com/ogen-go/ogen, go.opentelemetry.io/otel
oapi-codegen
  1 .go file(s), package bookshelf, go.mod written: no
  info.version 1.0.0 in the code: no
  header: Code generated by github.com/oapi-codegen/oapi-codegen/v2 version v2.8.2 DO NOT EDIT.
  modules it imports: github.com/oapi-codegen/runtime

With ogen, the release is the tag on the module that holds the --target directory, and the /v2 suffix is a line in a go.mod you write. Its getting started page records ogen itself as a tool dependency in that go.mod, so the generator version is pinned beside your own. Its configuration has no version option.

oapi-codegen works the same way from package and output in its configuration file, and its README shows the same go get -tool pinning. Its runtime module, github.com/oapi-codegen/runtime, is a second version your go.mod tracks. With either tool, check-releases.mjs is what enforces the rule across languages. Both beat sdkgen when Go is the SDK that matters and its module already releases with the service, because no template copy sits between your go.mod and your tag.

Check it worked

The test suite reads the committed generations and the release history, and covers the Python-only break that forces a Go major under lockstep and a misspelled change level that must not pass.

node --test versions.test.mjs
1..12
# tests 12
# suites 0
# pass 12
# fail 0
# cancelled 0
# skipped 0
# todo 0

When it goes wrong

The Go tag stays at the scaffold version. You set go to 2.0.0 and ran npm run generate, and TypeScript and Python moved while Go did not. The scaffold copied go/VERSION into .sdk/tm/go with the version filled in, and generate reuses that copy.

node versions.mjs generated/sdkgen/stale
generated/sdkgen/stale
  ts  package.json   1.3.0  sdk reports 1.3.0  tag ts/v1.3.0
  py  pyproject.toml 1.3.1  sdk reports 1.3.1  tag py/v1.3.1
  go  VERSION        0.0.1  sdk reports 2.0.0  tag go/v0.0.1   module github.com/voxgig-sdk/bookshelf-sdk/go
  3 problem(s)
    go: VERSION says 0.0.1, the SDK reports 2.0.0
    go: the Makefile tags go/v0.0.1, the SDK reports 2.0.0
    go: version 2.0.0 needs a module path ending in /v2

The generate printed one warning, and it names the fix:

WARN: model/sdkgen           generate-copies      target go: 1 file(s) in .sdk are unchanged copies, but @voxgig/sdkgen 4.44.3 has changed since they were copied, so this run generates from older templates. Run `npx voxgig-sdkgen package update @voxgig/sdkgen --no-fetch` to refresh them.

Run that refresh after every version change, then generate. A hand edit to go/VERSION does not survive the next generate.

The third problem in that output is a Go major without its suffix. The Go modules reference requires /v2 in the path of any v2 module, so a go/v2.0.0 tag on a path without it is not a valid version of that module. Add the module: path: line.

A release candidate stops the check with not a MAJOR.MINOR.PATCH version. That is deliberate: npm writes 1.4.0-rc.1 and PyPI normalizes it to 1.4.0rc1, so extend parseVersion with each registry’s spelling before you rely on it.

When not to do this

Do not hold strict lockstep when one language breaks more often than the others. Every Python break becomes a Go major, a fresh import path for every Go caller, for a change none of them can see.

Do not reach for sdkgen’s per-target versions when each language lives in its own repository with its own release owner. The overlay assumes one repository and one generate. Speakeasy’s version per language in gen.yaml, moved per target with speakeasy bump major -t typescript, fits that shape better.

Do not adopt a generator for versioning alone. If Go is your only SDK, ogen or oapi-codegen inside the service’s own module is less to run than any multi-language tool, and the module’s tags already are the policy.

Do not let the policy and the check disagree. If the text says minor-lockstep and CI runs independent, the check passes while the promise breaks.

Last verified

Verified 2026-11-21 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, ogen v1.25.0 and oapi-codegen v2.8.2, with Go 1.24.7 switching to the toolchain those two require. Every output block is what the command preceding it printed. The generations ran once, in generate.sh, and their files are committed under generated/. @voxgig/sdkgen 4.45.0 was run on the stale case too: it left go/VERSION at 0.0.1 with the same warning until the refresh, and added no /v2 suffix. Speakeasy was not run, and its version per language in gen.yaml is read from its documentation.

Footnotes

  1. Python has a version segment of its own for small corrections. PEP 440 permits post-releases, 1.4.0.post1, for minor errors that do not affect the distributed software, such as the release notes. It strongly discourages them for maintenance releases with actual bug fixes. A wheel missing py.typed changes what is distributed, so it is a patch, which is outside what the post-release segment is for. ↩︎ Back to text

  2. The Go modules reference gives the reason as the import compatibility rule. If an old package and a new package share an import path, the new package must be backwards compatible with the old one. A major version is therefore a different module path, and the reference says modules with distinct suffixes are treated as separate modules. Speakeasy’s versioning page downgrades a detected Go major to a minor unless the bump is forced. That keeps Go users on one path, at the price of moving the Go number away from the others. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.