Cross-Repo Release Runbook

How a change flows through the Verbara ecosystem from a version bump to a published, traceable release. Use this whenever a release touches more than one repo, or when SDK/Pro changes need to cascade downstream.

Authoritative per-repo detail lives in each repo’s release.yml / CI workflows and CHANGELOG.md. This runbook is the cross-repo sequence and the guardrails that the 2026-06-21 audit and ADR-0024 (the v2.4.2 shipping anomaly) showed we keep tripping over.

Dependency order (always release in this direction)

Verbara.Sdk (MIT)  →  Verbara.Sdk.Pro (private)  →  Verbara.Platform  ←  Verbara.Platform.Web
   NuGet                  NuGet                        Docker image          Docker image

A downstream repo can only consume an upstream change after the upstream package/image is published and its pin is bumped. Never release downstream against an unpublished upstream.

Guardrails (why releases have broken before)

A version bump is the release trigger. For Pro especially, merging to main without bumping Directory.Build.props PackageVersion is a silent no-op — nothing publishes.
Never docker push by hand. ADR-0024 (Platform v2.4.2) — a manual push with no git tag and no GitHub Release broke client traceability. Every shippable image goes through the release workflow that creates the tag + GitHub Release + signed (cosign) image.
CHANGELOG before tag. Several Pro releases (v2.0.0 / v2.0.1 / v2.2.0, then v2.6.0–v2.8.0) shipped with no CHANGELOG entry and were only caught months later. The CHANGELOG section must exist before the tag.
Version cascade lag is real. SDK v2.2.1 shipped while Pro/Platform stayed pinned to an older SDK. After an upstream release, immediately open the downstream pin bump.
Web audit gate drifts. A new npm/NuGet advisory can red-out main with no code change. Fix on main then rebase the release; don’t block the release on unrelated advisory drift.

Sequence

1. Upstream: Verbara.Sdk and/or Verbara.Sdk.Pro

Land the code on main, CI green, zero warnings.
Bump Directory.Build.props → PackageVersion (the release trigger).
Add the CHANGELOG.md section ## [X.Y.Z] - YYYY-MM-DD before tagging. To draft the Conventional-Commit-derived skeleton, copy ../../config/cliff.toml to the repo root and run git-cliff --unreleased --tag vX.Y.Z --prepend CHANGELOG.md, then curate the prose by hand (the CHANGELOGs stay hand-written; git-cliff only seeds Added/Changed/Fixed).
Let the release workflow publish the NuGet package (or, for local cross-repo dev iteration, use scripts/cross-repo-pack.sh to pack into the local feed and restore consumers).
Confirm the package version is actually published before touching downstream.

2. Cascade the pins downstream

After SDK ships: bump the SDK pin in Sdk.Pro and Platform (Directory.Packages.props). After Pro ships: bump the Pro pin in Platform. Then release those repos in order.

3. Downstream: Verbara.Platform (Native AOT Docker image)

Pins updated, CI green (AOT publish clean — 0 IL2026/IL3050/IL207x).
CHANGELOG section added; Directory.Build.props version bumped.
Release workflow builds + cosign-signs the AOT image, creates the git tag and GitHub Release, and records authorized digests. No manual docker push.

4. Downstream: Verbara.Platform.Web (React image)

npm run build (type-check + bundle) green; vitest green; i18n parity green; E2E green.
If the audit gate is red from advisory drift, fix on main and rebase (see guardrails).
CHANGELOG + version bump; release workflow builds + cosign-signs the image, tag + GitHub Release + authorized digests.

5. Close out

Move shipped plans to docs/plans/completed/ in the owning repo.
Archive closed-milestone Claude memory entries (ADR-0002 context hygiene).
Update the cross-repo shipped digest in docs/roadmap.md.

Per-release checklist

Copy ../templates/T5-release-checklist.md once per repo in a release that spans several. Run them in dependency order (SDK → Pro → Platform → Web).