update-demos

When this skill applies

The user asks, in any phrasing, to move the downstream demo/example repos onto a different Pulp SDK. Triggers include:

• "update the demos to the latest SDK"
• "rebuild the examples / demos using the latest version of the SDK"
• "do the new SDK build all the demos still?" / "check the demos still build"
• "bump every consumer's SDK pin to X.Y.Z"
• "open the SDK-update PRs for the demos"
• "republish the demo packages against the new SDK"

These are the Managed SDK Consumer Sweep — one registry of ~15 buildable downstream repos, driven by pulp minos {sweep,update,publish-runbook}. See the memory managed-sdk-consumer-sweep for the registry contents and history.

The registry lives in the private planning submodule

The consumer list is planning/sdk-consumers/consumers.yaml. A fresh public clone will not have it. If any pulp minos sweep|update|publish-runbook prints consumers registry not found, initialize the submodule first:

git submodule update --init planning

The tools also need PyYAML (python3 -m pip install pyyaml) — they print a clear install hint if it is absent.

The four-step flow

1. Resolve the target SDK version

"Latest" means the newest published SDK release, not necessarily what this checkout is at. Resolve a concrete X.Y.Z before doing anything:

pulp sdk available        # lists published SDK releases; newest is the target
# or, for the version this source tree builds:
pulp version              # SDK + project version of the current checkout

Pin the concrete version for the rest of the flow (e.g. --to 0.640.0). Never pass a floating latest to update — the pins written into consumer repos must be exact semver.

2. Verify every consumer still builds — pulp minos sweep

The sweep clones each buildable consumer, configures it against an installed SDK (find_package(Pulp) + CMAKE_PREFIX_PATH), builds it, measures every built artifact's min-OS floor, and reports build ok/fail plus floor-vs-SDK-floor drift. Non-zero exit on any build failure or drift.

# Build the SDK and install it to a prefix the sweep can point at:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
tools/ci/governed-build.sh cmake --build build
cmake --install build --prefix /tmp/pulp-sdk

# Dry-run first — prints the plan (what will build, what is skipped) without cloning:
pulp minos sweep --sdk-prefix /tmp/pulp-sdk --dry-run

# Real run (all buildable consumers), or narrow with --only:
pulp minos sweep --sdk-prefix /tmp/pulp-sdk
pulp minos sweep --sdk-prefix /tmp/pulp-sdk --only pulp-gpu-nam --json

Three repos (pulp-spectral-lab, pulp-superconvolver, pulp-tempo-sampler) are README/PKG-only release mirrors with no public source — the sweep skips them by design; that is not a failure.

3. Bump each consumer's SDK pin and open PRs — pulp minos update

update rewrites each consumer's SDK pin (pulp.toml sdk_version, find_package(Pulp X.Y.Z), FetchContent GIT_TAG v…; a floating latest pin is left alone). It is dry-run by default — you must pass --open-prs to clone, edit, branch, push, and gh pr create.

# See exactly which pins in which repos would change:
pulp minos update --to 0.640.0

# Actually open one chore/sdk-0.640.0 PR per repo:
pulp minos update --to 0.640.0 --open-prs

Review the dry-run diff before --open-prs. Merge the resulting PRs the normal way (each repo's own CI + review).

4. Republish the packaged demos — pulp minos publish-runbook

Packaged demos (signed PKG/DMG on public releases) are not auto-published — each has its own signing identity and release process. publish-runbook prints the per-repo rebuild → package → publish steps to run by hand after the pin PRs merge:

pulp minos publish-runbook --to 0.640.0

Guardrails

• Sweep before update. Don't bump pins the sweep hasn't proven build. A green sweep is the evidence that --to X.Y.Z won't break a consumer.
• update is dry-run until --open-prs; publish-runbook never mutates. Nothing pushes or publishes without an explicit flag / manual step.
• The floor can legitimately differ per repo. GPU NAM's heavier deps may floor above a simple demo — the sweep reports each repo's own floor; a floor above the SDK floor is information, only a floor below is drift.
• Use the SDK's declared cross-toolchain floor. Pulp currently pins macOS 13.4 because the macOS 15.4 SDK's libc++ makes the floating-point std::to_chars overloads reached by std::format unavailable below 13.4. Do not lower a consumer to 13.3 just because a newer SDK happens to compile the same source there; tools/deps/min_os.json is authoritative.
• Linux floors are architecture-specific. The m153 linux-x64 provider is measured at GLIBC 2.34. The m153 ARM64 V8 provider alone measures GLIBC 2.39 / GLIBCXX 3.4.32, while the combined ARM64 Skia/Dawn/V8 floor remains unknown. An ARM64 sweep must measure each final binary and must not reuse the x64 --max 2.34 ceiling or claim Ubuntu 22.04 portability.
• Measuring one binary's floor (no registry needed) is the primitive under all of this: pulp minos measure <path/to/binary> — also exposed over MCP as pulp_minos. See docs/guides/minimum-os-support.md.
• --workdir reuse is verified, not trusted. When sweep/update reuse an existing checkout in --workdir, they confirm its origin really is that consumer and fast-forward it to the remote tip first — a stale or wrong tree of the same name is refused, not measured or bumped as if it were current.

Related

• User guide: docs/guides/minimum-os-support.md
• CLI reference: docs/reference/cli.md (minos)
• Proposal / history: planning/2026-07-07-managed-sdk-consumer-sweep-runner-proposal.md
• Min-OS propagation into consumers: tools/cmake/PulpMinOs.cmake