> Documentation version: 3. [HTML page](maintenance.html)

<a id="manual-maintenance-tasks"></a>

# Manual maintenance tasks

The package compiler moves by itself, every day. Nothing else does. The tasks in
this chapter are the only way the repository’s tooling changes, and each is a
pull request a maintainer opens and reviews.

No workflow performs them on a schedule. A pull request opened by a workflow
with the repository’s ` GITHUB_TOKEN ` does not start CI, so an automated update
would arrive untested and wait for a maintainer anyway. More to the point, each
of these changes decides which code runs in CI, which is a decision to review
and not a chore to automate.

| Task | Files changed | When |
| --- | --- | --- |
| Update the lock | ` Blueprint.lock ` | To take newer tool versions, or to make a newer nightly selectable as ` roc-stable ` |
| Change the tooling compiler | ` Blueprint.roc `, the ` roc ` field of every script, sometimes ` Blueprint.lock ` | When scripts need a newer compiler, or periodically to stay close to current |
| Upgrade Blueprint | ` Blueprint.roc `, ` Blueprint.lock `, and the reviewed setup-action revision | For a new roc-blueprint release |
| Update script dependencies | Script headers, ` RocPackages ` in ` Blueprint.roc `, and ` Blueprint.lock ` when build sources change | For a new release of a platform or package the scripts use |
| Regenerate host bindings | A platform’s committed bindings | When ` ci.yml ` reports that the latest nightly generates different bindings |

<a id="risk-input-upgrades"></a>

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

<a id="update-the-lock"></a>

## 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](platforms.md#choose-the-correct-maintainer-path).

<a id="change-the-tooling-compiler"></a>

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

<a id="upgrade-blueprint"></a>

## 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 `](actions.md#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.

<a id="update-script-dependencies"></a>

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


<a id="regenerate-host-bindings"></a>

## Regenerate host bindings

See [Upgrade the bindings](platforms.md#upgrade-the-bindings).

<a id="maintain-released-utility-downloads"></a>

## 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](artifact-verification.md#verify-released-artifacts).

See [the complete adoption guide](pure-package.md#adopt-a-pure-package-without-nix) 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.