Skip to content

Module 09: Promotion, Registry Boundaries, and Auditability

Module Position

flowchart TD
  family["Reproducible Research"] --> program["Deep Dive DVC"]
  program --> module["Module 09: Promotion, Registry Boundaries, and Auditability"]
  module --> lessons["Lesson pages and worked examples"]
  module --> checkpoints["Exercises and closing criteria"]
  module --> capstone["Related capstone evidence"]
flowchart TD
  purpose["Start with the module purpose and main questions"] --> lesson_map["Use the lesson map to choose reading order"]
  lesson_map --> study["Read the lessons and examples with one review question in mind"]
  study --> proof["Test the idea with exercises and capstone checkpoints"]
  proof --> close["Move on only when the closing criteria feel concrete"]

Read the first diagram as a placement map: this page sits between the course promise, the lesson pages listed below, and the capstone surfaces that pressure-test the module. Read the second diagram as the study route for this page, so the diagrams point you toward the Lesson map, Exercises, and Closing criteria instead of acting like decoration.

Purpose of this Module

Recoverable state is not automatically trusted state. This module is where the learner separates exploratory, baseline, and promoted state and learns why downstream trust requires a deliberately smaller contract than the internal repository story.

Use this module to answer three questions clearly:

  • What exactly is being promoted for downstream use?
  • Which params, metrics, manifests, and files must travel with that promotion?
  • What evidence would another reviewer need to defend the released state later?

At a Glance

Focus Learner question Capstone timing
promotion boundary "What exactly is being trusted downstream?" inspect publish/v1/ once baseline and experimental state are already distinct
release evidence "Which params, metrics, and manifests must travel with a promoted result?" compare the publish bundle to dvc.lock and tracked metrics
auditability "Can another person defend this state later?" use verify as the proof loop, not just as a convenience

Proof loop for this module:

dvc status
dvc metrics diff
make PROGRAM=reproducible-research/deep-dive-dvc capstone-verify

Capstone corroboration:

  • inspect capstone/publish/v1/
  • inspect capstone/params.yaml
  • inspect capstone/dvc.lock
  • inspect Release Review Guide

The learner should leave this module able to say why promoted state is trusted more than baseline or exploratory state.

1) Table of Contents

  1. Table of Contents
  2. Learning Outcomes
  3. How to Use This Module
  4. Core 1 — Promotion Is a Contract, Not a Copy Step
  5. Core 2 — Stable Release Surfaces and Registry Boundaries
  6. Core 3 — Audit Evidence: Params, Metrics, Locks, and Manifests
  7. Core 4 — Reviewable Promotion Workflows
  8. Core 5 — Failure Modes in State Promotion
  9. Capstone Sidebar
  10. Exercises
  11. Closing Criteria

2) Learning Outcomes

By the end of this module, you can:

  • distinguish experimental state, baseline state, and promoted state clearly
  • define a stable release boundary around DVC-managed outputs
  • decide which params, metrics, manifests, and lock evidence must accompany a promoted result
  • design a reviewable promotion workflow that survives handoff and audit pressure
  • spot promotion shortcuts that make downstream trust impossible

Back to top

3) How to Use This Module

Set up a repository with these surfaces:

lab/
  dvc.yaml
  dvc.lock
  params.yaml
  metrics/
  publish/
    v1/

Then force yourself to name three categories of state:

  1. experimental outputs that are useful for exploration but not yet trustworthy downstream
  2. baseline outputs that remain comparable over time
  3. promoted outputs that downstream users are allowed to depend on

The teaching goal is not just to "publish files." It is to make the learner say exactly why one state is trusted more than another.

Back to top

4) Core 1 — Promotion Is a Contract, Not a Copy Step

Promotion should answer a question such as:

  • which model or report is now approved for downstream use?
  • which params and metrics define that promoted result?
  • which state is still exploratory and must not leak into a release boundary?

If promotion is treated as "copy the latest files somewhere stable," then the repository is quietly delegating trust to human memory.

Good promotion discipline:

  • a stable publish directory or release boundary
  • explicit params and metrics that explain what was promoted
  • a lockfile or equivalent state record tied to that promotion
  • a clear rule for when a new version is warranted

Back to top

5) Core 2 — Stable Release Surfaces and Registry Boundaries

A release surface should stay small and durable enough that downstream users do not have to know the internal repository layout.

Examples of a useful release surface:

  • a versioned publish/v1/ directory
  • a manifest naming the promoted files
  • a report that explains the run in human terms
  • parameters and metrics captured in their promoted form

The key distinction:

  • internal pipeline state helps the system operate
  • promoted state helps another person trust, consume, or review the result

Those are related, but they are not interchangeable.

Back to top

6) Core 3 — Audit Evidence: Params, Metrics, Locks, and Manifests

Auditability depends on enough evidence to answer:

  • what exactly was run?
  • which inputs and params mattered?
  • what metrics were observed?
  • which files form the promoted result?

Four surfaces matter especially in DVC:

Surface Why it matters
params.yaml shows the declared control surface
metrics makes comparisons reviewable
dvc.lock records the executed state graph
publish manifest tells a consumer what the release contains

If one of those is missing, a promotion can still happen. It just becomes much harder to defend later.

Back to top

7) Core 4 — Reviewable Promotion Workflows

A strong promotion workflow should be reviewable by another engineer who was not present for the experiment cycle.

That review should be able to answer:

  • what changed from baseline?
  • why is this promoted state better or more appropriate?
  • which artifact bundle is now the contract?
  • how would a future recovery drill restore this exact result?

Useful practice:

  • promote from an explicit baseline or experiment comparison
  • require verification before promotion
  • keep published artifacts stable enough for consumers and audits
  • document the downstream contract where a reviewer will actually see it

Back to top

8) Core 5 — Failure Modes in State Promotion

Practice identifying these failures:

  • the promoted report no longer matches the promoted params
  • metrics are diffed, but the compared runs are not semantically comparable
  • a release bundle exists, but the lock state needed to explain it is unclear
  • baseline and experiment outputs are mixed into one publish directory
  • a consumer depends on internal pipeline paths because the release surface is vague

Promotion failures are dangerous because they often look neat from the outside. The directory exists, the report renders, and the metrics are present. The problem is that the repository can no longer explain why that state deserves trust.

Back to top

9) Capstone Sidebar

Use the capstone to inspect:

  • publish/v1/ as the stable promoted surface
  • params.yaml and metrics/metrics.json as the semantic comparison surfaces
  • dvc.lock as evidence of the executed state graph
  • TOUR.md and the tour bundle as review artifacts for promoted state

Back to top

10) Exercises

  1. Define a stable publish boundary for one DVC repository and explain which internal paths are excluded.
  2. Promote one experimental result and write down exactly which params, metrics, and lock evidence justify it.
  3. Create a manifest for a promoted bundle and explain how a downstream user should validate it.
  4. Review a repository promotion story and list the top three reasons it would fail under audit.

Back to top

11) Closing Criteria

You pass this module only if you can demonstrate:

  • a clear distinction between exploratory state and promoted state
  • a stable release surface another consumer can trust
  • enough params, metrics, and lock evidence to defend a promoted result
  • a promotion flow that another reviewer can understand without private context

Back to top

Directory glossary

Use Glossary when you want the recurring language in this module kept stable while you move between lessons, exercises, and capstone checkpoints.