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

<a id="adopt-the-model-in-a-repository"></a>

# Adopt the model in a repository

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](overview.md#a-pure-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](pure-package.md#adopt-a-pure-package-without-nix). It includes a
complete Blueprint recipe, lock review, cache lifecycle and executable handoff.

<a id="risk-adoption-evidence"></a>

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

<a id="steps"></a>

## 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](shared-utilities.md#share-automation-through-executable-utilities)
   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](repository.md#write-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](software-bill-of-materials.md#publish-and-consume-software-bills-of-materials),
   including transitive components and exact subject digests;
   [` actions/sbom-sidecars `](actions.md#sbom-sidecars) and
   [` actions/fetch-dependency-sboms `](actions.md#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](optional-workflows.md#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](settings.md#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](settings.md#confirm-the-settings) describes.

<a id="acceptance"></a>

## Acceptance

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

- ` blueprint run check ` passes locally, using the released ` blueprint ` binary
  and a current nightly ` roc ` on ` PATH `.

- A search finds no ` .roc-version `, no ` roc: " ` header field outside ` scripts/ `, no committed flake
  files, no rendered documentation, and no Python, bash or PowerShell
  automation.

- ` ci.yml ` passes on the pull request, and its log shows the ` blueprint `
  checksum verified before ` blueprint run check `.

- A ` release.yml ` dry run produces every release asset, and the archived
  examples differ from the repository’s only in the package dependency.

- The dry run validates each SBOM’s schema, artifact/target digest and
  relationships, and a query identifies a known transitive component and its
  source. Documented coverage gaps are reviewed; the release process makes the
  documents and signature evidence available downstream.

- A manual ` nightly.yml ` run passes against the latest release.


- A deliberately failing nightly run opens exactly one tracking issue, a second
  failure comments on it, and a passing run closes it.

- ` blueprint run check-settings -- <owner>/<name> `, run from roc-automation,
  passes every line for the repository.

- A real pull request with a failing check is blocked from merging.


- For a platform: a deliberate edit to the committed bindings fails ` ci.yml `.