# How to propagate a template change to every SDK repo that uses it

> Release a template fix as a package version, dry-run it in every SDK repository, land it as a branch in each, and treat a repository with no diff as forked.

Source: https://voxgig.com/howto/propagate-a-template-change-across-sdk-repos

- Audience: platform-team
- Level: advanced
- Languages: typescript
- Verified: 2026-11-22
- Published: 2026-11-22

## 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](/howto/package-a-shared-generator-customisation).

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Fern `generatorVersion` and Replay](https://buildwithfern.com/learn/sdks/current/reference/sdk-config) | 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](https://github.com/git/git/blob/master/contrib/subtree/git-subtree.adoc) | 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`](https://learn.microsoft.com/en-us/openapi/kiota/using) | 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](https://github.com/voxgig/sdkgen/blob/main/docs/how-to/use-an-sdkgen-package.md) | 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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/cli.md) | 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.

```ts title="packages/acme-sdkgen-trace@1.1.0/.sdk/tm/ts/src/feature/acmetrace/AcmetraceFeature.ts"
    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`](https://docs.npmjs.com/cli/v10/commands/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.

```js title="classify.mjs"
  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.

```bash
node report.mjs
```

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

```bash
node others.mjs
```

```text output
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](https://learn.microsoft.com/en-us/openapi/kiota/design) 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](https://buildwithfern.com/learn/llms.txt) 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`](https://buildwithfern.com/learn/cli-api-reference/cli-reference/sdk-commands).
Local edits survive through [Replay](https://buildwithfern.com/learn/sdks/current/overview/custom-code),
which reports a conflict in the regeneration pull request, or `.fernignore`, whose files stop
receiving updates at all. The [pricing page](https://buildwithfern.com/pricing.md) puts custom
code on the Enterprise plan.

## Check it worked

The suite classifies the committed diffs and checks each record.

```bash
node --test rollout.test.mjs
```

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

- [Package a customization several SDK projects can install](/howto/package-a-shared-generator-customisation)

- [Take over a bundled SDK target and maintain it yourself](/howto/move-a-bundled-target-out-of-the-tree)

- [Find hand edits in a generated SDK before you regenerate](/howto/find-hand-edits-before-regenerating)

- [Push one CI template change to five hundred repositories](/howto/push-one-ci-change-to-many-repositories)

- [Shorten the regenerate loop while you edit a template](/howto/shorten-the-regenerate-loop-while-editing-templates)

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

[^1]: The [`git subtree` documentation](https://github.com/git/git/blob/master/contrib/subtree/git-subtree.adoc)
explains `--squash` with 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 `--squash` lets a project switch back and
forth between versions rather than strictly forward, which makes a rollback one more pull.

[^2]: Kiota's [support page](https://learn.microsoft.com/en-us/openapi/kiota/support) targets minor
releases at the first Tuesday of every month. Its
[changelog](https://github.com/microsoft/kiota/blob/main/CHANGELOG.md) 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.