Your request-id template sends one id on every call, and you fixed it in one repository. Five repositories need the fix. One edited that template locally, one copied it by hand, and one installs it from a checkout nobody pulls. A rollout that reports success in each cannot tell you which repositories received the change.
What you get
You will end up with a template fix released as a package version, rolled out as one branch per repository, and a report that sorts every repository into five outcomes. This is for you if you own templates that several SDK repositories generate from.
Short answer
Release the fix as a version of an sdkgen package, then script the rollout. In each repository,
install the release and run voxgig-sdkgen package update with --dryrun, then run it for real on a
branch, regenerate, and diff the generated SDK. Sort each result into an expected diff, a conflict, a
refusal, or no diff, and chase every no-diff repository, because its update reported success.
You will need
Node 22 or later, git, and two or more SDK repositories generated from one set of templates.
Verified 2026-11-22 against @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3,
@voxgig/apidef 8.32.4, Kiota 1.38.0 and 1.39.0, and git 2.43.0. Packaging the template is
covered in package a customization several SDK projects can
install.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
Fern generatorVersion and Replay | Fern generates the SDKs and you want regeneration pull requests | No templates of your own, and Replay’s custom code needs the Enterprise plan | You own the template, not the generator |
git subtree of the template folder | Templates live in their own repository and every SDK repository vendors them | A version only as a commit hash, and a hand copy it refuses to pull into | You need a changelog and a rollback per release |
Kiota update and kiota-lock.json | The change is a Kiota release, and every client records its parameters in a lock | No templates, and an update that removes hand edits while reporting success | Your change lives in a template you wrote |
| scripted regeneration pull requests | Any of these, driven across every repository with one script | A script to own, and a classifier that must know what the change looks like | Two repositories, where a person reads both diffs |
| sdkgen package update | sdkgen projects that install a shared package from npm | Every fix waits for a release, and its dry run missed the one conflict | You need the fix in a repository within the hour |
Voxgig maintains sdkgen. The page compares its package update with four other ways to ship a fix.
A versioned package gives you a changelog, a rollback and a copy record in each repository, at
the price of a release for every change. A git subtree pull is instant and records only a commit. Kiota and
Fern have no templates for you to change, so their rollout is a generator version, and the
script’s job is the same: classify each repository’s diff before anyone merges it.
Release the fix as a package version
The fix is one line of the feature’s template, in @acme/sdkgen-trace 1.1.0. 1.0.0 minted an id in
init, so every call carried the same one.
spec.headers = spec.headers || {}
// 1.1.0: one id per request. 1.0.0 minted one id in init and sent it on every call.
spec.headers[this._options.header || 'X-Request-Id'] = randomUUID()
}
}
generate.sh packs both versions with npm pack
and sets up five scratch repositories on 1.0.0. orders and billing install from npm. catalog
does too, then edits the line the fix touches. ledger copied the feature into its own .sdk, and
returns added it from a checkout beside the project by a relative path.
Dry-run, branch, and classify every repository
rollout.mjs installs the release in each repository and runs the update with --dryrun, then
puts every tracked file back. Then it creates rollout/acme-sdkgen-trace-1.1.0 in each, updates for
real, regenerates, and passes the exit status and git diff -- ts to the classifier.
const { update, diff } = result
if (update.exit !== 0) {
const conflict = /cannot take the incoming copy/.test(update.error ?? '')
return { outcome: conflict ? 'conflict' : 'refused', detail: (update.error ?? '').split('\n')[0] }
}
if (diff.trim() === '') return { outcome: 'no diff', detail: 'treat as forked or stale until shown otherwise' }
The rollout ran once, from generate.sh. report.mjs classifies the committed diffs again and
prints what each repository reported.
node report.mjs
@acme/sdkgen-trace 1.1.0, branch rollout/acme-sdkgen-trace-1.1.0
repo dry run update SDK files changed outcome
orders-sdk exit 0 exit 0 3 expected diff
billing-sdk exit 0 exit 0 3 expected diff
catalog-sdk exit 0 exit 1 0 conflict
ledger-sdk exit 1 exit 1 0 refused
returns-sdk exit 0 exit 0 0 no diff
which release each says it has: package list, then the copy record in .sdk/log/copies.jsonl
orders-sdk before: @acme/sdkgen-trace@1.0.0, copies 1.0.0 after: @acme/sdkgen-trace@1.1.0, copies 1.1.0
billing-sdk before: @acme/sdkgen-trace@1.0.0, copies 1.0.0 after: @acme/sdkgen-trace@1.1.0, copies 1.1.0
catalog-sdk before: @acme/sdkgen-trace@1.0.0, copies 1.0.0 after: @acme/sdkgen-trace@1.1.0, copies 1.0.0
ledger-sdk before: (unrecorded), copies none recorded after: (unrecorded), copies none recorded
returns-sdk before: @acme/sdkgen-trace@1.0.0, copies 1.0.0 after: @acme/sdkgen-trace@1.0.0, copies 1.0.0
orders-sdk on 1.0.0: two calls, same request id: true
orders-sdk on 1.1.0: two calls, same request id: false
The two npm repositories changed three generated files: the feature and two documents that print its version. A compiled orders SDK sent a fresh id per call afterwards.
catalog is the edited one. It exited 0 on a dry run that printed
1 locally-changed file(s) will take the update by merge. The real update printed
1 locally changed file(s) cannot take the incoming copy, so nothing was changed, exited 1,
and named log/conflict/ as the place of the incoming copy. ledger was refused with “Nothing installed from @acme/sdkgen-trace”, because package list
shows its feature as (unrecorded) and the copy record has no entry for it. returns printed
“updated” and changed nothing, because its checkout still holds 1.0.0.
Roll out the same fix from a template repository or a Kiota release
The same release went into four repositories as a git subtree of the template folder, and Kiota
moved three generated clients from 1.38.0 to 1.39.0 with kiota update.
node others.mjs
git subtree pull --squash of the template folder, v1.0.0 -> v1.1.0
orders exit 0 merged release v1.1.0
billing exit 0 merged release v1.1.0
catalog exit 1 conflict in acmetrace/AcmetraceFeature.ts release v1.0.0
returns exit 1 fatal: can't squash-merge: 'acmetrace' was never added. release none recorded
kiota update with 1.39.0, on clients generated by 1.38.0
orders exit 0 Update of 1 clients completed successfully lock 1.39.0 changed: client/kiota-lock.json
billing exit 0 Update of 1 clients completed successfully lock 1.39.0 changed: client/kiota-lock.json
catalog exit 0 Update of 1 clients completed successfully lock 1.39.0 changed: client/kiota-lock.json, client/models/index.ts
removed: // catalog: a hand edit to a generated file
git subtree reports its conflict and its hand copy, but its record of a version is a commit hash
in the squash message, mapped to a tag here.1 Kiota builds code from a code model rather than templates, as its design
page explains, so a Kiota rollout is a
generator version. It writes kiotaVersion into each kiota-lock.json, which answers which
repository has which release, and on this document 1.39.0 changed nothing else. In the edited
repository it removed the hand edit and still reported success, so only the diff shows it.2
Fern’s documentation index lists no templates of
your own either, only custom code. Its current configuration, sdk-config.yml, runs the
newest generators unless a target pins generatorVersion, and the legacy generators.yml moves
with fern generator upgrade.
Local edits survive through Replay,
which reports a conflict in the regeneration pull request, or .fernignore, whose files stop
receiving updates at all. The pricing page puts custom
code on the Enterprise plan.
Check it worked
The suite classifies the committed diffs and checks each record.
node --test rollout.test.mjs
1..11
# tests 11
# suites 0
# pass 11
# fail 0
# cancelled 0
# skipped 0
# todo 0
One test feeds the classifier three neighbors of the orders diff and expects unexpected diff for
each. One turns the removed line into context, one adds a changed line to the feature, and one adds
a changed file.
When it goes wrong
The dry run is green and the real run conflicts. In 4.44.3, withCopyMerge in
dist/helpers/copymerge.js skips the merge guard on a dry run, so --dryrun reports the planned
merge without trying it. Treat a dry run as a check of which files would move, then let the real
run on a branch decide. The refusal names two ways on: fold the change in by hand and rerun with
--keep, or take the release with --force.
A repository names a release it does not have. In catalog’s working copy after the refusal,
package list reported 1.1.0, the version npm had installed, while .sdk/log/copies.jsonl still
said 1.0.0. Read the copy record when you audit versions.
Every generate in returns warns that 1.0.0 “has changed since they were copied” even though
the checkout never moved, from the first generate on. The same checkout added by its absolute path
gave no warning, so the relative path causes it, and the update does not clear it. doctor printed
.sdk matches the scaffold and exited 0. Pull the checkout before every rollout, or install from npm instead.
When not to do this
Do not package a template that two repositories share. A release, a changelog, and a copy record
cost more than reading two diffs, and a git subtree covers that case.
Do not merge a rollout branch whose outcome is no diff. In this run returns printed success with
a stale source. On a Kiota release that changes no output, no diff is the right result, so tell the
classifier what the release changes.
Do not use sdkgen’s package update for a fix that must reach a repository today. Kiota, Fern, and a
git subtree pull move as soon as you run them, and Kiota’s lock records the version without a release
of your own. The newest sdkgen and apidef releases gave the same dry run, conflict, and warning.
Related how-tos
Last verified
Verified 2026-11-22 against Node 22.23.5, git 2.43.0, @voxgig/create-sdkgen 0.31.9,
@voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, and Kiota 1.38.0 and 1.39.0, with the catalog and
returns repositories run again on @voxgig/sdkgen 4.45.0 and @voxgig/apidef 8.33.1.
generate.sh ran every rollout in scratch repositories, twice with the same records, and committed
what the commands read. Fern was not run, since it generates on its own service or in Docker: its version settings,
Replay and plans come from its documentation as fetched that day.
Footnotes
-
The
git subtreedocumentation explains--squashwith an example of its own: people rarely want to see every change between v1.0 and v1.1 of the library they use. It adds that--squashlets a project switch back and forth between versions rather than strictly forward, which makes a rollback one more pull. ↩︎ Back to text -
Kiota’s support page targets minor releases at the first Tuesday of every month. Its changelog dates 1.38.0 to November 2, 2026, a Monday, and 1.39.0 to November 17, so the month’s first Tuesday fell between the two releases this page ran. ↩︎ Back to text