This chapter is for a maintainer bringing a repository in line with the model. It assumes the earlier chapters. Work from a fresh branch of the remote default branch, and open one pull request per numbered step so that a failure points at one change.

A Roc package follows every step, with one runner in each workflow. The sentences below that begin "A platform" and the acceptance item that begins "For a platform" do not apply to it.

For a Roc package using released utilities and fixed downloaded tooling, start with Adopt a Roc package without Nix. It includes a complete Blueprint recipe, lock review, cache lifecycle and executable handoff.

Risks and controls for adoption evidence§

Copying a starter can leave stale paths, unrelated task names or missing product cases while producing plausible configuration. Adopt through observable behavior. Run the documented local tasks, a release dry run and the published suite; inspect the resulting files and test the required-check and issue-reporting failure paths. Keep configuration-specific fixes in the adopting repository and common fixes in the shared tool. Adoption evidence establishes the exercised integration, not every feature of the product or every future utility version.

Steps§

  1. Environment. Add Blueprint.roc and Blueprint.lock with the shared utilities and every tool and toolchain the repository uses. Add roc-stable and source dependencies only for tooling the repository itself runs from source. Using the released blueprint binary, confirm that its named tasks run the selected utilities. Remove any flake.nix, flake.lock, .envrc or other environment definition this replaces, and add .blueprint/ to .gitignore.

  2. Tasks. Use the shared utility skeleton for common operations. Configure Blueprint tasks rather than copying their implementations. Consolidate overlapping scripts and delete one that only repeats another test. Keep product-specific source tooling in Roc following Write product-specific automation as Roc scripts. Carry each script’s tests across first, as expect tests or cases the check script runs. Delete the original only when its replacement runs in CI.

  3. Pins. Remove .roc-version, .github/roc-nightly.json and every roc header field outside scripts/. Set the roc field of every script to the roc-stable tag. Make the check script enforce both. A platform also commits its generated host bindings and adds the check that regenerates and compares them.

  4. Examples. Point every Roc application in the repository at the working tree by relative path. Record expected output. Remove any step that rewrites committed examples after a release.

  5. Release artifacts. Add tasks that build the bundle, the examples archive, the documentation archive and the manual, and a task that tests the archive against a loopback bundle. Generate and locally validate an SPDX or CycloneDX SBOM for each final artifact as described in the SBOM contract, including transitive components and exact subject digests; actions/sbom-sidecars and actions/fetch-dependency-sboms do this with a reviewed sbom/composition.json. Arrange immutable downstream distribution and authenticated evidence without granting write permissions to jobs executing repository code.

  6. Workflows. Replace the repository’s workflows with ci.yml, release.yml and nightly.yml, plus any optional workflows it needs. Call actions/setup-blueprint with no inputs, after the checkout; it installs the release that Blueprint.roc names. A repository that tests on Windows or Intel macOS names a roc-blueprint release that publishes a binary for that system, lists the system in its Systems, and leaves install-nix unset in those jobs.

  7. Repository settings. Apply Repository settings, update the required check names, and delete branches that earlier automation owned. Confirm the result with the check-settings task, as Confirm the settings describes.

Acceptance§

Record a link for each item in the final pull request.