# 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.

Source: https://voxgig.com/howto/lockstep-or-independent-versions-across-sdk-languages

- Audience: api-producer
- Level: intermediate
- Languages: typescript, python, go
- Verified: 2026-11-21
- Published: 2026-11-21

## 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](/howto/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

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Hand-maintained version table](https://semver.org/spec/v2.0.0.html) | A different generator per language, or a release every few months | Someone edits the table every release, because no check fails on a skipped row | Your tags already say everything the table would |
| [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen) | Go is the SDK, and its module is released with the service that owns it | One generated file and no `go.mod`, so every version decision is your module's tag | The other languages need the same number from the same tool |
| [`ogen`](https://ogen.dev/docs/intro/) | A Go client with typed optional fields and OpenTelemetry already wired in | A generated package with no `go.mod` or version, so the rule lives outside the tool | You want one tool to stamp every language's manifest |
| [sdkgen](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) | One model generates TypeScript, Python and Go into one repository | A version key per target, a copy refresh before Go's tag moves, and a hand-set `/v2` path | Each language has its own repository and its own release owner |
| [Speakeasy](https://www.speakeasy.com/docs/sdks/manage/versioning) | Independent versions, with the tool proposing each language's bump on every generation | An account, and bumps read from `info.version`, a checksum and generator changes, not your surface | Strict 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]

```json title="policy.json"
{
  "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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md)
lists, so one key sets all three targets.

```aontu title="generated/sdkgen/lockstep/model/project.aontu"
# 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.

```bash
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.

```bash
node versions.mjs generated/sdkgen/lockstep generated/sdkgen/independent
```

```text output
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](https://go.dev/ref/mod#major-version-suffixes) 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.

```bash
node check-releases.mjs policy-lockstep.json releases.json
```

```text output
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`:

```bash
node check-releases.mjs policy.json releases.json
```

```text output
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`:

```bash
node go-tools.mjs
```

```text output
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](https://ogen.dev/docs/intro/)
records `ogen` itself as a tool dependency in that `go.mod`, so the generator version is pinned beside
your own. Its [configuration](https://ogen.dev/docs/config/) 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.

```bash
node --test versions.test.mjs
```

```text output
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.

```bash
node versions.mjs generated/sdkgen/stale
```

```text output
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:

```text title="generated/sdkgen/stale/generate-warnings.txt"
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.

## Related how-tos

- [Release every port of a library on one version number](/howto/release-every-port-on-one-version)

- [Choose a release automation tool for an SDK repository](/howto/choose-a-release-automation-tool-for-an-sdk)

- [Detect breaking changes between two OpenAPI versions in CI](/howto/detect-breaking-changes-between-openapi-versions-in-ci)

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

- [Decide if a regenerated SDK is a minor or major release](/howto/regenerated-sdk-minor-or-major-release)

## 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.

[^1]: Python has a version segment of its own for small corrections.
[PEP 440](https://peps.python.org/pep-0440/) 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.

[^2]: The [Go modules reference](https://go.dev/ref/mod#major-version-suffixes) 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](https://www.speakeasy.com/docs/sdks/manage/versioning) 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.