Manual maintenance tasks§

Risks and controls for input upgrades§

An upgrade can change executable code through a URL, digest, transitive input or compiler selection without an obvious change to the product. Treat new identities as reviewed input changes. Update the declared recipe and lock, inspect the resolved artifacts and run the affected tasks before adopting them. Compiler and binding updates remain explicit maintainer work. The resulting checks establish the selected combinations. Matching an upstream revision or passing compatibility tests does not establish that an input is unaffected by known vulnerabilities; advisory analysis uses its own component evidence.

Update the lock§

1. Run blueprint update, or blueprint update <input> to move one input and keep every other pin.

2. Run blueprint run check.

3. Open a pull request whose only changed file is Blueprint.lock.

4. Merge after ci.yml passes.

A lock update moves the overlay revision, the package source and tool versions. It never changes which release is roc-stable, because that tag is written in Blueprint.roc. It does not change the blueprint binary or the platform URL.

Where the repository fingerprints native build inputs, a lock change can make those inputs stale. ci.yml reports that, and the fix is a new linker-input release in the same pull request; see Choose the correct maintainer path.

Change the tooling compiler§

1. Choose a published nightly release.

2. Change the tag in the Command("roc-stable", ...) setting of Blueprint.roc.

3. Change the roc field in every script header to the same tag. The check script fails until they all match.

4. If the locked overlay revision predates that release, run blueprint update roc and commit Blueprint.lock in the same pull request.

5. Fix any script the new compiler breaks in that pull request, so the tag and the scripts move together.

6. Merge after ci.yml passes.

This is a maintainer’s decision for each repository. Repositories need not agree.

Upgrade Blueprint§

A release’s blueprint binary must be used with that release’s platform URL. actions/setup-blueprint reads the release from that URL. Keep that selection in one place while migrating configuration and locked inputs together:

1. Choose a roc-blueprint release.

2. Move the workflows' reference to actions/setup-blueprint to a revision that records that release, if the current one does not. Dependabot proposes this change; actions/setup-blueprint explains where the checksums are reviewed.

3. Change the platform URL in the Blueprint.roc header.

4. A repository that generates sidecars with actions/sbom-sidecars also needs a revision that records the release’s SBOM tool in actions/setup-blueprint/sbom-tools.json: the app bundle and its compiler, the reviewed SHA-256 of each blueprint-sbom-<system> binary the release ships, and its features (members, manifest) as its release notes state them. With binaries recorded the action needs no compiler; otherwise the tool runs on the release’s blueprint compiler-version, so update that fixed compiler recipe with it.

5. Migrate configuration to the release’s supported Spec and run blueprint check.

6. Run a full blueprint update when the release changes the lock format, review changed identities against the previous lock and commit the regenerated lock.

7. Remove generated .blueprint/ state when the release requires it.

8. Run the affected named tasks and merge after ci.yml passes.

External tools should read blueprint lock show --json, validate its public report format and use content_identity and namespaced provider metadata. Do not parse the internal representation of Blueprint.lock. Consumers of build reports use build_identity; report and package versions are separate compatibility contracts. Run cold and warm provisioning checks and exercise corrupt-cache recovery: a successful lock conversion alone does not demonstrate that the selected programs execute correctly.

Update script dependencies§

1. Change the release URL in each script header that uses the dependency.

2. Change the same URL under RocPackages in Blueprint.roc, and add any new dependencies of that dependency. roc-stable deps scripts/check_all.roc lists them.

3. For sandboxed builds using those bundles, run blueprint update, review the changed source identities and commit Blueprint.lock. Task-only bundles are pinned by their committed URL hashes and do not change the lock.

4. Run the affected tasks and merge after ci.yml passes.

Regenerate host bindings§

See Upgrade the bindings.

Maintain released utility downloads§

For Roc packages, Programs and Fetch lock released utilities and fixed tooling without Nix. Change the utility recipe in Blueprint.roc, run blueprint update, review per-system URLs, hashes, lengths and download hosts, and commit the lock. Keep the package compiler floating independently. Native platforms can retain Nix sources and sandboxed builds for their toolchains.

The shared artifact cache key changes with the lock and installer/registry identity. Separate logical tool subsets use separate cache-workload values, so an immutable compiler-only cache cannot claim the docs cache key. Restored artifacts are rehashed before use and extracted trees/task links are rebuilt; cache hits do not authenticate executables. Routine use needs no remote attestation service. Review provenance when adopting a release, following released artifact verification.

See the complete adoption guide for the tested cold/warm workflow and persistent executable handoff. The shared setup’s install-nix option defaults to false; opt in where the selected tools/builds need Nix.