Skip to content

Tutorials that edit lab/config paths must be rewritten or archived in the lab/ removal change; tutorial check is dry-run-only in CI #257

Description

@jeremi

Part of the 1.0 release-readiness push (see release/READINESS.md). Found during the 2026-07-07 YAML config audit. Companion to #224 (lab/ pre-removal track).

Context

Three published tutorials instruct readers to clone the repo and edit specific lab/config/*.yaml files:

  • docs/site/src/content/docs/tutorials/configure-dhis2-claim-checks.mdx (cd registry-stack/lab, edit config/source-adapter/dhis2-health-sidecar.yaml and config/notary/dhis2-health-notary.yaml, ~lines 279-337)
  • docs/site/src/content/docs/tutorials/getting-started-fhir-evidence.mdx (config/notary/fhir-health-notary.yaml, ~lines 208, 237)
  • docs/site/src/content/docs/tutorials/first-run-with-registry-lab.mdx (live compose instructions plus a tag-pinned blob link into lab/config/notary/shared-eligibility-notary.yaml, line 228)

No automated signal fires when those paths disappear: root CI runs check-tutorial.sh in --dry-run only (it asserts the extracted command count), the full execution mode runs nowhere, and the script's default REGISTRY_LAB_PATH ($REPO_ROOT/../registry-lab, where REPO_ROOT is docs/site) predates the monorepo layout and points at a sibling checkout that does not exist.

Scope

  • Rewrite these tutorials against the replacement lab (Solmara) or archive them, in the same PR that removes lab/, not after.
  • Fix or retire check-tutorial.sh's path assumptions; decide whether full-execution mode should run anywhere (relates to Execute the registryctl tutorials end to end in CI #212, which covers the registryctl tutorials).

Acceptance

  • After lab/ removal, no published page instructs edits to paths that no longer exist.
  • The tutorial checker either exercises tutorials for real somewhere, or its dry-run-only status is documented as the accepted guarantee.

Security note

If this work surfaces a suspected vulnerability, report it per SECURITY.md; do not post details on this issue.

Metadata

Metadata

Assignees

No one assigned

    Labels

    1.0-blockerBlocks the 1.0 release intent.area:docsDocumentation site ownership.area:labRegistry Lab ownership.documentationImprovements or additions to documentation

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions