Skip to content

Change Impact Check & Diff Reports

Intent

Generate diffs and impact reports when artifacts change; validate downstream; publish migration notes.

Structure

Change impact checks and diff reports are a structural safety net for evolution. Structurally it combines semantic diffs, an impact checklist, and downstream validation runs so teams understand the blast radius of change.

  • Diff engine: generates diffs for StructureDefinitions and terminology artifacts, highlighting semantic changes
  • Impact checklist: standard prompts for authors to assess downstream impact (servers, SDKs, partners)
  • Downstream run: one or more representative downstream builds/validators executed in pinned environments
  • PR integration: attach diffs to PRs and require checklist completion for risky areas
  • Release artifacts: store diffs and impact summaries with releases and migration notes

Key Components

Diff tooling

  • Generate diffs for StructureDefinitions and terminology artifacts
  • Highlight semantic changes (requiredness, bindings, slices)
  • Store diffs with CI artifacts and releases
  • Make diffs reviewable in PRs
  • Use diffs to prevent accidental breaking changes

Impact checklist

  • Define a standard checklist for change impact
  • Include downstream systems, tests, examples, terminology
  • Require owners to confirm impact assessment
  • Track checklist completion in PR templates
  • Use checklist as a release readiness input

Downstream validation run

  • Run a representative downstream build/validation
  • Use pinned environments to keep results stable
  • Record failures with actionable logs
  • Gate releases on downstream health
  • Track deltas across releases

Behavior

Assess → validate → communicate

The behavior is to prevent accidental breaking changes and to make intentional breaking changes explicit and supported.

On every meaningful change

  1. Generate diffs and review them for semantic impact.
  2. Complete the impact checklist and identify affected downstream consumers.
  3. Run the downstream validation job and capture logs as artifacts.

When impact is high

  1. Decide whether a breaking version bump is required.
  2. Write migration guidance with before/after examples.
  3. Communicate timelines and deprecation windows to implementers.

Benefits

  • Fewer regressions
  • Transparency

Trade-offs

  • Extra automation required