Skip to content

RELEASE_RUNBOOK.md

Latest commit

 

History

History
146 lines (100 loc) · 5.79 KB

RELEASE_RUNBOOK.md

File metadata and controls

146 lines (100 loc) · 5.79 KB

Release Runbook

This runbook is the shortest path from a merged branch to a credible research-first public checkpoint.

It is not a clinical deployment checklist. It is the operator path for making the repo's proof, validation, and pilot evidence easy to audit.

1. Confirm Release Intent

Before you tag or announce anything, confirm the release is still framed as:

  • research-use workflow software
  • explainable and benchmarkable
  • human-review dependent
  • non-clinical in its claims

If the release narrative drifts from those boundaries, stop and fix the messaging first.

2. Refresh The Core Proof Surface

Run:

make validate-strict
make benchmark-demo

If the checked-in public proof should move with the release, also run:

make refresh-demo-proof

Record:

  • the validation date
  • the make validate-strict summary
  • the current API test count
  • whether the published benchmark snapshot changed

3. Decide Whether Pilot Smoke Evidence Must Be Refreshed

You should refresh pilot evidence when the release changes any of the following:

  • import behavior
  • auth or site-scope behavior
  • import-run audit visibility
  • pilot overlay wiring
  • hosted smoke workflow behavior

If none of those changed, note that the prior hosted and local evidence is being carried forward intentionally.

4. Capture Hosted Smoke Evidence

The hosted workflow is:

The minimum hosted evidence path, already satisfied by the recorded March 25, 2026 runs below, is:

  1. Manually dispatch Pilot Smoke with smoke_scope=fhir-success-only.
  2. Download or inspect:
    • pilot-smoke.log
    • pilot-smoke-summary.json
    • pilot-smoke-summary.md
  3. Build a bundled hosted evidence record from the downloaded summary artifacts:
    • make pilot-smoke-evidence SUMMARY_DIR=/path/to/downloaded/pilot-smoke-artifacts HL7_DECISION=pending
    • This writes pilot-smoke-evidence.json and pilot-smoke-evidence.md next to the downloaded artifacts unless you override OUT_DIR, OUT_JSON, or OUT_MARKDOWN.
  4. Record the exact run date, run URL, duration, outcome, and visible-case summary in:

Historical failed workflow executions without jobs or uploaded artifacts do not count as hosted evidence. Treat the first usable hosted checkpoint as the first green run that actually produces pilot-smoke-summary.json and pilot-smoke-summary.md.

Current recorded baseline:

  • FHIR-only hosted confirmation: #23563902873 succeeded on 2026-03-25 with summary artifacts pilot-smoke-summary-header-demo-fhir-smoke and pilot-smoke-summary-proxy-demo-fhir-smoke
  • HL7-only hosted trial: #23564057337 succeeded on 2026-03-25 with summary artifacts pilot-smoke-summary-header-demo-hl7-smoke and pilot-smoke-summary-proxy-demo-hl7-smoke
  • Current HL7 decision: keep HL7 manual-only in the default hosted matrix because the trial proved operability, but the weekly hosted matrix remains intentionally narrower to control recurring runtime and maintenance cost

If you are making the HL7 hosting decision for Phase 6B, also dispatch:

  1. smoke_scope=hl7-success-only
  2. compare its duration and stability to the FHIR-only hosted path
  3. rerun make pilot-smoke-evidence SUMMARY_DIR=/path/to/downloaded/pilot-smoke-artifacts HL7_DECISION=keep-manual or HL7_DECISION=promote-default
  4. record whether HL7 should stay manual or join the default hosted matrix

5. Refresh Local Manual Evidence When Needed

The hosted workflow is intentionally narrower than the full operator matrix.

If your change touched failure-path or visibility behavior, rerun the relevant local overlay smokes from docs/DEPLOYMENT.md, especially:

  • shared-visibility
  • failed-run shared-visibility
  • structured adapter failed-run shared-visibility
  • audit-visibility
  • structured adapter audit-visibility
  • structured adapter site-rejection

Record only the paths that were actually rerun. Do not imply broader coverage than what was executed.

6. Update Release-Facing Docs

Before opening or merging the release-facing PR, make sure these stay aligned:

7. Draft Release Notes

Use:

Fill in:

  • what the release enables
  • what remains out of scope
  • exact validation date and headline results
  • exact hosted smoke evidence or the explicit reason it is still pending
  • the best setup path for a new collaborator
  • the highest-priority next slice after release

8. Minimum Credible Release Evidence

Treat a release candidate as credible only if all of the following are true:

  • make validate-strict is green
  • the benchmark proof surface is still reproducible
  • the hosted/manual smoke boundary is explicitly documented
  • the latest hosted FHIR evidence is either recorded or clearly marked pending
  • any still-manual HL7 hosting decision is stated plainly
  • the docs do not reference missing files or stale setup paths

9. Current Post-6C Reality

As of the current Phase 6 state:

  • repo-side interoperability hardening is already in place
  • the hosted smoke evidence boundary is now recorded and should be carried forward intentionally unless a newer rerun supersedes it
  • release-facing docs should help contributors understand that boundary without private context