SDK Changelog Generation

Generate changelogs for SDK pod packages following the monorepo GitFlow.

When to use this skill

Applies to SDK pod packages whose paths are owned by .github/teams/sdk.json.

Use when:

• Preparing a release for any SDK pod package
• User asks to generate changelog
• User asks to create human-readable/presentable changelog
• User asks to generate CHANGELOG_LLM.md
• User invokes /qv-sdk-changelog

Workflow

Every step is mandatory. Do not ask the user whether to do CHANGELOG_LLM.md or NOTICE — they are part of this skill and always run.

Step 1: Identify Target Package

If the user doesn't specify, ask which SDK pod package they want to generate a changelog for.

Package slugs match git tags (sdk, inference, cli, ai-sdk-provider, opencode-plugin, openclaw-plugin, …). Directory resolution (including plugins/*) is in scripts/sdk/package-paths.cjs.

On a release train (qv-release-train), run this once per train package; the changelogs land on the one train branch. Step 7 differs there.

sdk and inference are lockstep on major.minor. Two changelogs, two releases, engine first: --package=inference for release-inference-<x.y.z>, then --package=sdk for release-sdk-<x.y.z>. Both notes for the same x.y.z share one display floor: the last lockstep version already shipped (patch or .0). --base-commit is that version's backmerge on main so the new notes do not repeat it. Use the same floor on both packages; splitting them (inference from the previous .0, SDK from a later patch) duplicates patch notes and makes the files disagree.

--base-commit is only the generate range, not the full set of notes. See Step 2 when that floor is a patch.

The SDK is the consumer-facing full notes. --package=sdk also scans packages/inference (CHANGELOG_EXTRA_SCAN_DIRS in scripts/sdk/package-paths.cjs). The inference changelog is the engine-only slice of that same set. A patch on either side is one release of its own.

Working branch (when cutting from a release line): use chore/<pkg>-<x.y.z>-changelog (e.g. chore/sdk-0.17.0-changelog). Do not name the head release-*: the cli / ai-sdk-provider / plugin publish workflows trigger on push to release-* and publish to npm. The release cut itself must be three-part release-<pkg>-x.y.z. Full rules live in qv-sdk-pr-create → "Release PR branch naming".

Step 2: Fetch Tags and Resolve Base

Tags live on the upstream remote (tetherto/qvac), not the contributor's fork. The script fetches from upstream first, falling back to origin.

Full-history requirement (fail-stop): discovery is git log <base>..HEAD -- <packagePath>. Before generating:

1. git rev-parse --is-shallow-repository must be false (else git fetch --unshallow / re-clone without --depth, then stop).
2. Base must be an ancestor of HEAD (git merge-base --is-ancestor <base> HEAD); otherwise check out the release tip / package tag first.

The generator enforces both checks and exits non-zero on failure.

Nested worktrees: unset GIT_DIR GIT_WORK_TREE before any git or changelog command, or the generator runs against the parent repo.

Pick --base-commit, then pass it. Do not run the generator unflagged and hope auto-detect is right.

• Lockstep sdk + inference: always pass --base-commit / --base-version — the last lockstep ship's backmerge on main, same floor on both packages. Never tag auto-detect: inference-v* is often not an ancestor of main, and a minor auto-detects the previous .0 (repeats already-shipped patch notes). When that floor is a .0, generate is enough. When it is a patch, generate from the patch backmerge, then union main-only work from the previous lockstep .0 backmerge → that patch backmerge: first-parent merges touching packages/inference or packages/sdk, minus [skiplog], minus PR numbers already in packages/sdk/changelog/<patch>/CHANGELOG.md. Hand-add to both changelogs (CHANGELOG.md and breaking.md / models.md / api.md when the PR tag requires them). --update-root-changelog only after that.

git log --first-parent --format='%s' <prev-lockstep-.0-backmerge>..<patch-backmerge>
# keep subjects whose merge diff touches packages/inference or packages/sdk

• Standalone (cli, plugins, anything not lockstep): omit the flags. The generator auto-detects (minor → previous .0, patch → highest tag). Cutting a patch behind current needs --base-version passed explicitly. A previous .0 still includes main-only work in the patch window; drop PR numbers already in changelog/<patch>/ if they re-list. If no tags exist, ask for --base-commit and --base-version.

--base-commit is only the generate range. The published-version audit after generate is the consumer delta, for every package.

Step 3: Generate Raw Changelog

Lockstep (sdk / inference) always passes the floor from Step 2:

node scripts/sdk/generate-changelog-sdk-pod.cjs --package=<name> --base-commit=<sha> --base-version=<version>

Standalone packages can omit the flags (auto-detect):

node scripts/sdk/generate-changelog-sdk-pod.cjs --package=<name>

The script automatically excludes:

• PRs tagged [skiplog].
• Backmerge PRs (subjects starting with Backmerge or Merge release …). Backmerges merge a release branch back into main; their content is already documented in the release branch's own changelog, so listing them here is noise.
• PRs whose title fails the SDK PR-format validator (these are warned, not silently dropped — fix the title and re-run, or surface to the PR author).

For [mod] PRs, the script extracts the Added/Updated/Removed model lists from the PR body and renders them as indented continuation lines beneath the bullet in CHANGELOG.md (each section on its own line — never inline as one giant row). It also writes models.md.

CHANGELOG.md inline lines may stay at MAX_INLINE_MODELS (5) plus (and N more). models.md is the full added/removed set — never truncated. PR bodies are often incomplete; if the published-version audit disagrees, replace models.md from the export/constant diff, not from the PR body.

If this package's public API is those exported constants, removed names are breaking: they go in breaking.md even when the PR was only [mod].

The extractor applies two policies (in this order):

1. Companion entries are dropped. Companions are auxiliary files that ship alongside a primary model but aren't independently usable — vocab files, lexicons, raw data shards, metadata blobs. The filter recognises constant suffixes (*_LEX, *_VOCAB, *_DATA, *_METADATA) and any free-form description containing the word "companion". Only first-class models reach the changelog.
2. Entry-count suffixes are stripped. (N entries) / (N entries — short note) decorations are removed from the displayed text — readers can follow the models.md link for exact counts.

After both filters, each section is trimmed to MAX_INLINE_MODELS (currently 5) entries, with (and N more) for the remainder. Example:

- Regenerate model registry. (see PR [#123](...)) - See [model changes](./models.md)
  Added: NMT_Q0F16, NMT_Q4_0 (and 12 more)
  Removed: MARIAN_OPUS_*

If after filtering a section is empty, it's omitted. If all sections are empty the bullet emits with no continuation lines.

After generate: published-version audit (mandatory)

git log <base>..HEAD is the generate range. It is not the consumer delta.

For every SDK pod package, after the raw files exist:

DIR=$(node -e "console.log(require('./scripts/sdk/package-paths.cjs').getPackageDir('<slug>'))")
PKG=$(node -e "console.log(require('./${DIR}/package.json').name)")
LAST=$(npm view "$PKG@<base-version>" gitHead)
git diff "$LAST" HEAD -- "$DIR"

<base-version> is Step 2's --base-version (the version this cut supersedes). Do not npm view "$PKG" version: that is dist-tag latest, which is a different line when you cut a patch behind current.

sdk-v* tags are not the published commit (create-github-release.yml omits target_commitish, so the tag lands on main). gitHead is packed with the tarball. Fail-stop if npm view cannot resolve. Diff $DIR, not package.json: exports, serve/HTTP routes, and exported constants live in source. Every user-facing add, remove, or rename in that diff must appear in api.md, breaking.md, and/or models.md. Hand-add. --update-root-changelog only — do not re-run a full generate. New public exports under an older umbrella PR still get their own api.md example.

Fail-stop until the notes match the tree. Then write CHANGELOG_LLM.md.

Step 4: Generate CHANGELOG_LLM.md (mandatory)

Always run this step. Do not ask the user — it's part of the skill.

Author CHANGELOG_LLM.md from changelog/<version>/ after the published-version audit, not from git log. Title and NPM line are this package (@qvac/<pkg>), not always sdk.

See references/changelog-llm-format.md.

Skip backmerges, automated bumps, and entries that only repeat a previous release. Models body stays concise; the full constant lists live in models.md and in the LLM ### Added / ### Removed blocks.

After writing the file, rebuild the root aggregate so packages/<package>/CHANGELOG.md picks up CHANGELOG_LLM.md (the aggregator prefers it over CHANGELOG.md):

node scripts/sdk/generate-changelog-sdk-pod.cjs --package=<name> --update-root-changelog

Do not re-run a full generate after the published-version hand edits — that overwrites api.md / breaking.md / models.md.

Format the generated markdown (mandatory). CHANGELOG_LLM.md is authored by hand here, so it is the file most likely to carry markdown formatting issues that a committed-file format check would later reject. Every SDK pod package uses prettier (format = prettier --check ., format:fix = prettier --write .) with .prettierrc set to "prettier-config-holepunch". Never --no-config. CI ([inference] format, [sdk] format, …) loads holepunch; --no-config or a different parser (quote style, trailing commas) is the usual red we hit.

npx prettier fails with Cannot find package 'prettier-config-holepunch' when that package is not resolvable, then either skips or formats with a fallback CI rejects. Never --no-config. Do not npm install in a package whose range names an unpublished lockstep dep (e.g. sdk waiting on inference) — run npx prettier from a sibling that already has node_modules.

DIR=$(node -e "console.log(require('./scripts/sdk/package-paths.cjs').getPackageDir('<name>'))")
npx prettier --check "$DIR/changelog/<version>/**/*.md" "$DIR/CHANGELOG.md"

Scope those globs to this package. Do not run changelog/**/*.md from the repo root or another package cwd — that walks every historical version folder.

If it reports problems, fix them — npx prettier --write on the same paths, or npm run format:fix — and re-run the check until it passes clean. Do this before moving on so the release commit carries only prettier-clean markdown.

Downstream rendering note: the docs site reads CHANGELOG_LLM.md verbatim and inlines it under a ### @qvac/<pkg> subsection of the release-notes page of the SDK's current documentation line (one reference/release-notes.mdx per line — see docs/website/docs-workflow.md). Each headline you write becomes a section header on the public docs site (with two levels of demotion to fit the nesting), so phrase them as standalone reader-facing prose, not internal categories. Keep headings emoji-free (e.g. ## Breaking Changes, not ## 💥 Breaking Changes) — emoji prefixes leak verbatim into the public headers; the only allowed emoji is the 📦 **NPM:** line. See the format guide for the full rule.

Step 5: Generate announcement-post.txt (mandatory)

Always run this step after Step 4. It produces a Slack-ready copy-paste post at packages/<package>/changelog/<version>/announcement-post.txt.

The file is gitignored (packages/*/changelog/*/announcement-post.txt) — it's a local working artifact, not a committed deliverable. Never git add it.

node scripts/sdk/generate-changelog-sdk-pod.cjs --package=<name> --generate-announcement-post

The script emits the short Slack template — header + three links + optional breaking-changes block + footer. Per-section bullet lists are intentionally omitted; readers follow the full-changelog link for the detail.

Layout:

• :qvac: SDK <version> :rocket: NPM Public release header.
• NPM, GitHub release, and full-changelog tree links.
• :warning: Breaking Changes section with link to breaking.md — emitted when breaking.md exists (including hand-added catalog-as-API removals). File presence, not [bc] tags and not CHANGELOG.md.
• Footer: Thanks to everyone on QVAC team :green_heart: :qvac: :green_heart:.

If the post needs hand-tuning (e.g. a custom note for a specific release), edit the file directly. It's gitignored, so changes won't pollute the diff.

Step 6: Update NOTICE file for the target package

After Step 5 completes, run notice-generate for the same --package to ensure its NOTICE file reflects any dependency changes in the release:

source .env
node .agents/skills/qv-notice-generate/scripts/generate-notice.js <package-name>

If JS npm install fails (unpublished lockstep dep, registry miss), do not commit a NOTICE whose JS section is empty. Restore the JS block from HEAD and keep any successful model-scan additions. Models-only packages still update model attributions against the last published NOTICE.

Do NOT commit the announcement post (gitignored) and let the user review the rest before committing.

See .agents/skills/qv-notice-generate/SKILL.md for full details.

Step 7: Set the @qvac/inference version (only when --package=sdk)

@qvac/sdk shares a major.minor with the @qvac/inference range it depends on, and tetherto-qvac-sdk is generated from @qvac/sdk at the same version. An sdk release sets both and regenerates the Python client (SDK_VERSION and the other _generated/ outputs). Skip this step for any other --package value — an --package=inference release does not touch the SDK.

On a release train nx release version has already written the @qvac/inference range; only regenerate the Python client (Step 3 of qv-sdk-inference-version).

Read and follow .agents/skills/qv-sdk-inference-version/SKILL.md (Steps 1–4). Short form:

npm view @qvac/inference@<x.y.z> version
node .agents/skills/qv-sdk-inference-version/scripts/set-inference-version.mjs --engine-version=<x.y.z>

cd packages/sdk-python
.venv/bin/python3 scripts/generate.py
.venv/bin/python3 scripts/generate.py --check

<x.y.z> is the @qvac/inference version this release ships against, already published. Include sdk-python generated updates in the release commit. The Python client does not get its own changelog — history lives in packages/sdk/CHANGELOG.md.

Step 8: Generate site docs (only when --package=sdk)

Generate the documentation-site API reference and release notes for the new version in the same working tree, so the changelog PR also carries the docs update. This replaces the old standalone docs-release.yml workflow (which opened a second, separate docs PR). Skip this step entirely for any other --package value — only the SDK release drives the versioned docs site.

Generation is deterministic: it runs the existing docs/website scripts (TypeDoc + Nunjucks render + verbatim CHANGELOG_LLM.md inlining). No LLM is involved in producing the API reference or release notes here — Step 4 already authored CHANGELOG_LLM.md, and this step only renders it into the site.

Precondition — the line is already cut (fail-stop):

The site publishes one documentation line per SDK minor: a folder under content/docs/sdk/ holding a complete page tree. The current line's folder is parenthesised — (v0.21) — and answers the version-less paths; every older line's is plain. The line for the version you are releasing was cut by the documentation engineer right after the previous release deployed, so it already exists when you reach this step.

The generators write into the current line, read from docs/website/src/lib/versions.ts. They refuse a version that is not that line's, before writing anything:

Refusing to write v0.21 pages into v0.20, the current line of /sdk.
  v0.21 has no line yet. Cut it before documenting the release:
    bun run scripts/cut-line.ts sdk v0.21

That message means the cut has not happened. STOP and ask the documentation engineer to cut the line. Do not run the cut inside a release PR, and do not work around the refusal — without it, the release notes of the version that already shipped are overwritten, and the build and the test suite both still pass.

Prerequisites:

• docs/website dependencies installed (cd docs/website && npm install).
• SDK_PATH set in docs/website/.env pointing at the SDK package root (packages/sdk, the directory containing index.ts and tsconfig.json). Copy docs/website/.env.example to .env if it doesn't exist yet. CHANGELOG_REPO_ROOT defaults to the repo root, so no override is needed when running inside the monorepo.

1. Generate the API reference + release notes. Which commands depends on whether this is a minor or a patch.

Minor (X.Y.0) — render both pages:

cd docs/website
bun run scripts/generate-api-docs.ts <version> --force-extract
bun run scripts/generate-release-notes.ts <version>

Patch (X.Y.Z, Z >= 1) — append the ## vX.Y.Z section and leave the API summary alone, because the public API is frozen at the minor boundary:

cd docs/website
bun run scripts/generate-release-notes.ts <version> --append-patch

Either way it writes only, with (v<X.Y>) the current line's folder:

• docs/website/content/docs/sdk/(v<X.Y>)/reference/api.mdx (minor only)
• docs/website/content/docs/sdk/(v<X.Y>)/reference/release-notes.mdx

Nothing else. src/lib/versions.ts and public/_redirects belong to the cut, not to a release — a release must leave both untouched.

Those paths are generated here on release. Capability/CLI/config/runtime prose is /qv-docs-update on the feature PR. Do not hand-edit reference/**.

2. Verify the site still builds (mandatory):

cd docs/website
npm run build

A clean build confirms nothing on the website broke. Treat a build failure as fail-stop: surface the error and do NOT proceed to commit until it's fixed.

Staging follows the same convention as the other steps. Like every other step, this one only generates files — it never runs git add or git commit. The pages above are part of the release commit (same as Step 7's version files: "Include … in the release commit"), and every generation/build byproduct is gitignored — exactly like Step 5's announcement-post.txt — so a normal git status review shows only the committable files. Let the user review before committing. Generated + gitignored byproducts (do not git add them):

• docs/website/scripts/api-docs/api-data.json (written by generate-api-docs.ts)
• docs/website/.next/, .source/, out/, dist/ (from npm run build)
• docs/website/next-env.d.ts
• packages/sdk/dist/ (from the prebuild:examples build step)

See docs/website/docs-workflow.md for the full pipeline reference.

CLI Parameters

Output

Generates changelog files in packages/<package>/changelog/<version>/:

• CHANGELOG.md - Main changelog
• breaking.md - Breaking changes ([bc] PRs and catalog-as-API removals)
• api.md - API changes ([api] PRs and published-version export/route diffs)
• models.md - Model changes (full set; [mod] PRs and constant diffs)
• CHANGELOG_LLM.md - Human-readable version (always generated, see Step 4)
• announcement-post.txt - Slack copy-paste post (always generated, see Step 5, gitignored — never commit)

Additionally:

• packages/<package>/CHANGELOG.md – Aggregated changelog containing all versions (newest → oldest), preferring CHANGELOG_LLM.md (human-readable) from each version folder when available, falling back to CHANGELOG.md

When --package=sdk, Step 8 also generates the documentation-site pages of the SDK's current documentation line (commit these alongside the changelog), with (v<X.Y>) its folder:

• docs/website/content/docs/sdk/(v<X.Y>)/reference/api.mdx – API reference MDX, minor releases only
• docs/website/content/docs/sdk/(v<X.Y>)/reference/release-notes.mdx – Release notes MDX

Nothing else. The version manifest (src/lib/versions.ts) and the redirects (public/_redirects) belong to the line cut, which happens outside a release.

Tag Format

Tags follow the pattern: <package>-v<x.y.z> and are created on upstream (not the fork).

Examples:

• sdk-v0.8.0 (minor — used as base for next minor release)
• sdk-v0.8.1 (patch — used as base for next patch release)
• rag-v2.0.0

Repeated mistakes

These have gone red on more than one SDK-pod changelog PR. Fix them before push, and keep this list to things that are cheap to prevent:

• Prettier is holepunch, not stock. .prettierrc is "prettier-config-holepunch". Never --no-config. Resolve holepunch from a package that can install; do not npm install against an unpublished lockstep dep. Quote style and trailing commas on CHANGELOG_LLM.md are the usual fail.
• Lockstep: pass the floor. Never run the generator unflagged for sdk / inference. Same --base-commit on both. When that floor is a patch, union the Step 2 main-only window. SDK is the consumer set; inference is the engine slice.
• inference-v* is often not on main. Use the backmerge SHA, not the tag.
• Nested worktrees inherit GIT_DIR. unset GIT_DIR GIT_WORK_TREE before generate/commit/cherry-pick, or you operate on the parent repo.
• Push the org remote (upstream when that is tetherto/qvac), not the contributor fork. git push with no remote follows origin.
• Do not skip SDK Pod Checks. Workspace red vs published red is a real signal; [skip-sdk-pod-checks] is not the changelog fix.
• Notes vs --base-version gitHead, not only git log. After generate, audit exports / routes / constants against npm view "$PKG@<base-version>" gitHead. Do not use sdk-v* or npm latest. git log <base>..HEAD misses work that is already an ancestor of --base-commit.
• NOTICE JS wipe. A failed npm install must not replace the JS section with zero deps. Restore JS from HEAD; keep successful model-scan adds.

Quality Checklist

Before completing:

• Correct package identified
• Working head (if branched for the release PR) is chore/<pkg>-<x.y.z>-changelog, not release-*
• Clone is not shallow (git rev-parse --is-shallow-repository → false)
• Base reference resolved (tag or --base-commit) and is an ancestor of HEAD
• For lockstep sdk + inference: both generated with the same --base-commit / --base-version (last lockstep display floor); never unflagged auto-detect; SDK changelog includes the engine slice
• When that floor is a patch: main-only window unioned in on both changelogs
• GIT_DIR / GIT_WORK_TREE unset (or pointed at this worktree) so generate/git did not run in a parent repo
• PRs scoped to package path only
• Changelog files written to correct version directory
• CHANGELOG_LLM.md authored from changelog/<version>/ after the published-version audit (this package's name on the title/NPM line)
• Generated markdown is prettier-clean with prettier-config-holepunch resolved (never --no-config; do not npm install against unpublished lockstep deps)
• announcement-post.txt generated (mandatory, gitignored)
• Published-version audit done: npm view "$PKG@<base-version>" gitHead vs HEAD under getPackageDir(<slug>) ($DIR, not package.json) matches api.md / breaking.md / models.md
• models.md is the full added/removed set (inline CHANGELOG.md may still use (and N more)); catalog-as-API removals are in breaking.md
• NOTICE updated; JS section not emptied by a failed install
• When --package=sdk: qv-sdk-inference-version run (engine version published, sdk version and @qvac/inference range sharing a major.minor, sdk-python regenerated), python generate.py --check passing
• When --package=sdk: the line for this version was already cut (no generator refusal), site docs generated via generate-api-docs.ts + generate-release-notes.ts, npm run build passed, and git status shows only that line's reference/api.mdx (minor) and reference/release-notes.mdx as committable docs changes — never src/lib/versions.ts or public/_redirects (byproducts gitignored)
• Root CHANGELOG.md rebuilt from all version folders (and picks up CHANGELOG_LLM.md)
• Versions sorted in descending semver order
• No duplicated versions
• Root file is deterministic (fully regenerated)
• Org remote (upstream when that is tetherto/qvac) is the push target, not the fork

References

• SDK pod ownership: .github/teams/sdk.json
• GitFlow and PR format: docs/gitflow.md
• LLM changelog format: references/changelog-llm-format.md
• NOTICE generation: .agents/skills/qv-notice-generate/SKILL.md
• sdk @qvac/inference version: .agents/skills/qv-sdk-inference-version/SKILL.md
• Docs site pipeline (Step 8): docs/website/docs-workflow.md
• Release PR branch naming (org release-* push / Merge Guard): .agents/skills/qv-sdk-pr-create/SKILL.md