Skip to content

Release Process

This is what an IG owner does to turn merged FSH into a published version. Contributors do none of it — see Contributing and feedback.

It is published rather than kept internal for two reasons: if you have contributed FSH, this is what happens to it next; and if you are implementing against a released version, this is what "released" guarantees about the artifacts you consume.

Five commands

Command When What it does
npm run build every owner-track PR The gate. Compiles the IG with SUSHI, regenerates every consumer (TypeScript, Python, C#, and the docs/fhir/ pages of this site), then runs 18 read-only checks over the result -- example conformance, version agreement, canonicals, the export boundary, published URLs, invariants, and a check that regenerating changed nothing. No IG Publisher, no site build.
npm run build <x.y.z> cutting a version The same gate, with the version written into sushi-config.yaml and the changelog heading rewritten first. Use <x.y.z>-candidate to mark a branch as unreleased. Cutting lives here, in the cheap local command, so a failed cut leaves an ordinary working tree.
npm run test before a release, and after touching the library The library's own suite: the Python, .NET and TypeScript ports, patient-synth, and the cross-verifier. It runs no CQL tests: the library's CQL engine is not something a published IG depends on, and its tests run in the library's own CI. publish runs it too, because the site states the library version that generated it; running it on its own first finds a failure before the release is cut.
npm run site previewing Builds the site into .build/site/ and publishes nothing.
npm run publish publishing Release readiness, the gate, the library suite, package.tgz, the site build, the push, and a check that the live site really serves every artifact. Add --dry-run to do everything except the push, --fast to verify with TypedFhir in process rather than the HL7 validator, --with-publisher to also run the IG Publisher as a cross-check.

Run the target, not the steps. The chain has an order that matters and every way of getting it wrong is silent -- it publishes something subtly wrong rather than failing. bin/publish.ts has the specifics if you need to debug it; nobody should have to hold them in their head.

There is no way to publish without the gate. The verification runs inside publish rather than beside it, so there is no flag that ships unchecked content.

If you changed a ^copyright, publish with --with-publisher. The IP-statements page is rendered from a fragment the IG Publisher emits (.build/temp/pages/_includes/ip-statements.xhtml), and gen-about keeps the committed page when no fresh fragment is present -- so without the publisher a licence change does not reach the rendered page. bin/check-export-boundary.ts fails the gate when a licence statement denies what the rendered page does.

package.tgz is built by bin/pack.ts rather than by the IG Publisher, and the QA half of what the publisher used to provide is now bin/check-canonicals.ts in the gate. The publisher remains available as a cross-check; it is not on the critical path.

Publishing happens before the PR is opened. That is deliberate: readers see the current spec without waiting on review. The published site is therefore allowed to be ahead of main.

The release, in order

Every release takes these steps, in this order. Each one ends in something you can check; do not start the next until it does. The judgement steps (2, 6) are described in full under What the target cannot do.

  1. Bring in main. git fetch and merge origin/main into the release branch, so every contribution merged since the branch was cut is in the release. Resolve generated files by regenerating, not by hand. Then audit the merge: list every path and every append-only file (the changelog above all) that lost lines, and account for each. A dropped changelog section passes every gate. Check: the audit names nothing you cannot explain.
  2. Review what came in. Read each contribution against conventions.md (step 1 below). If one does not conform and the fix is not mechanical, stop: bounce it to its author rather than rewriting it inside the release. Check: every contribution is accepted, fixed, or bounced.
  3. Run the gate: npm run build. Contributor branches cannot regenerate the shared surface, so expect to commit regenerated output here. Check: green, and git status clean.
  4. Run the library suite: npm run test. publish runs it again, but a failure found now costs nothing; found at step 8 it costs a re-cut. Fix what is simple; stop on anything that is not. Check: it exits 0.
  5. Start the preview and keep it running: npm run site -- serve, which serves the site at http://127.0.0.1:8000/ and rebuilds on every edit. Every review from here on is of the rendered pages, not the source: the changelog at /changelog.html, and every profile, intro and guide page the release touched. Links, anchors and tables only fail where they render. Check: the home page answers and reads the candidate version.
  6. Write and review the changelog (step 4 below). Read the section as one release note, reshape it to the house form, then have it reviewed by someone who did not write it, against the best previous entries, for narrative, completeness and consistency. Iterate with the release owner, in the preview, until both are satisfied. Check: the owner signs off on the rendered page.
  7. Cut it: npm run build <x.y.z>, no -candidate. Check: green, the changelog heading is dated today, and git status is clean after committing.
  8. Publish: npm run publish -- --dry-run, then npm run publish (add -- --with-publisher if a ^copyright changed). It is a release to app partners; the owner confirms before the push. Run every command from step 3 on with GITHUB_BASE_REF=main set. Without it the blast-radius check measures from the commit the branch was created at, so a release branch cut from the previous release and then merged with main reports every application change main brought in as its own reach. Check: the live site, not the local build: /, /package.tgz and /packages/nexus-<x.y.z>.tgz answer 200, and the home page reads the new version.
  9. Open the PR to main, as a draft, with the gate's generated-surface summary (.build/surface-summary.md) in the body and a sentence for every removal saying whether it was intended.
  10. Announce as soon as the live site serves the new version (see Then); merge and tag when the pull request is approved, then open the next version.

What the target cannot do

Four things need judgement. They are the release.

1. Review the scope

Work a release ticket (FHIR-*) that names it. Collect the FSH merged or queued since the last release and review each change against conventions.md: one profile per file, file-size caps, portable FHIRPath invariants over unevaluable slices, canonical URLs are forever. Fix or bounce anything that does not conform, and clean up contributor FSH — naming, must-support policy, duplicated modelling, stray experimental content.

Breaking profile changes, canonical-URL changes and edits to src/ig/ig.ini or src/ig/sushi-config.yaml are T3 review tier: a second owner reviews.

2. Check the change reached every surface

A spec change is not done until its surroundings catch up. Most of this is checked for you — the gate tells you what is missing; writing it is yours:

  • Examples — every profile ships at least one conforming example. Enforced: the gate fails if a profile has no instance declaring it in meta.profile.
  • Seed corpus — new must-support elements need generated data. Enforced: the coverage guarantee fails, in both directions (IG surface the corpus misses, corpus surface the IG does not model).
  • Narrative — the profile's src/pages/StructureDefinition-<id>-intro.md, and the handbook page for the feature. Enforced: the gate fails if a profile has no intro page. Every profile has one as of 1.15.0, so a missing page means the change in front of you added a profile without writing about it.
  • Validator — add an explicit rule only where regeneration cannot infer the constraint. This one is genuinely judgement: no check can tell you that a constraint needs a hand-written rule.

3. Bump the version

src/ig/sushi-config.yaml is the AUTHORITY for the version, and as of 1.25.0 it is the only file that carries it by hand. Everything else derives: the facade ports hold it in IG_META / IgMeta and are rewritten by the regenerate step, ts/codegen/lib/ig-specs.ts reads it from the compiled IG, and worked CQL examples declare bare using Nexus, which resolves whichever model is vendored. (manifest.json is fork provenance and never carries the version.)

npm run build <x.y.z> cuts it -- writing the authority, rewriting the changelog heading, and regenerating, in that order and in one command:

npm run build 1.21.0-candidate   # start work on 1.21.0
npm run build 1.21.0             # cut it, changelog heading dated today

check-version-agreement.ts is the gate. It asserts the generated stamps against the authority, so a tree that was stamped but not regenerated fails naming the file, both versions, and the command that fixes it. Generated file banners no longer carry the version (as of 1.23.0), and the rendered reference pages under docs/fhir/ are not tracked, so neither is a place a bump has to reach.

Breaking change = major, additive = minor, fix or docs only = patch — except while this IG is status: draft, which it currently is.

The draft carve-out. While sushi-config.yaml says status: draft, a breaking change bumps MINOR, not major. The spec is still stabilizing and no external party depends on it; applying the strict rule now would spend major versions on the ordinary work of getting the model right. 1.12.0 alone renamed two invariant keys and added two required bindings, each technically breaking — a 3.0.0 inside one month would assert something false about the spec's maturity. Version numbers communicate; while nothing depends on us, the changelog does the communicating.

Three obligations come with it, none optional:

  • The changelog entry names the break and states the consumer action ("consumers validating against the old invariant key must update it"). A silent breaking change inside a minor is the failure mode this rule risks; the entry is the mitigation.
  • Breaking changes stay T3 review tier regardless of the digits. The carve-out is about numbering, not scrutiny.
  • When status: leaves draft the carve-out ends, and whoever flips it updates this section in the same PR.

Version numbers ending in 13 are not used — see the 1.13.0 section between 1.14.0 and 1.12.0 in the Changelog. This applies to TypedFhir's version line as well, which went 0.12.0 → 0.14.0 alongside 1.19.0. Skipping in only one of the two lines would leave a reader hunting for an artifact that was never cut.

The -candidate marker

A branch that is not being released carries <x.y.z>-candidate, and the gate's last step (bin/check-release-ready.ts) fails every branch that does not. That is the normal state of work in progress, not a defect: before the marker existed, the 1.20.0 branch read 1.19.0 everywhere, and anything handed to someone from it was misnamed as a release that had not happened.

Step 17 is LAST on purpose. Everything above it -- conformance, all four ports, the coverage guarantee, the cross-verifier -- has already reported by the time it speaks, so a branch under development gets the whole gate and one line saying the version is not releasable. Cutting the release is npm run build <x.y.z> without the -candidate suffix, and it is the last thing you do, not the first.

4. Write the changelog entry

You do not move the heading by hand. npm run build <x.y.z>, from step 3, rewrites the in-flight ## [x.y.z-candidate] - unreleased heading in CHANGELOG.md to ## [x.y.z] - <today> as part of the same command that writes the version into every site. This step is about the CONTENT under that heading, not the heading. The TypedFhir version that generated the release is not recorded here: the IG metadata page reads it from backend/lib/TypedFhir/ts/package.json when the site is built.

set-version.ts renames the in-flight heading; it does not create one, and it accepts two spellings -- ## [Unreleased] and ## [x.y.z-candidate]. That matters twice. Starting the NEXT release from a freshly cut one means the top heading is dated and there is nothing to rename, so the cut reports no ... heading to rename and you add one by hand before re-running. And an outside contributor branching from a released state has the same problem with no way to know the version, so the contributor guide tells them to open ## [Unreleased] and leave the number to you -- expect that spelling in their PRs and rename it here rather than asking them to change it.

The entries themselves are written as the work lands, not assembled here -- every owner-track PR adds its own. What this step is for is reading them together, once, as the release note a consumer will actually get: are the breaking ones marked breaking, in bold, with the consumer action spelled out? Is anything consumer-visible missing? The changelog carries this specification's compatibility contract in place of SemVer, so completeness is a correctness question and the preamble says so.

Write for the reader of the release — converter authors, bot developers, integrators. It records what changed in the model, what changed in the artifacts they consume, and any migration warning. It is not a build log: internal tooling gets one line, or none.

Every release section has the same shape, so a reader learns it once:

  • An opening paragraph, its first sentence in bold, saying what the release is about and whether it breaks anyone.
  • Summary bullets, in this order and only where they apply: BREAKING (one per break, naming who it breaks), New, Changed, Fixed, and Am I affected?, which tells each kind of reader what to do and ends by saying who needs to do nothing.
  • ### Added, ### Changed, ### Fixed, each holding #### entries whose heading states the change as a fact. Each entry opens with a See: line linking every artifact it touches, says what changed and why, marks itself Additive. or BREAKING, and ends with Producer action and Consumer action lines, "none required" included.

Contributions arrive as flat bullets, sometimes with a ticket marker; fold them into this shape and drop the markers.

Then

Announce the version as soon as the live site serves it, without waiting for the merge — the new version, the headline changes, any consumer-facing notes (breaking changes, new must-support elements, deprecations), and a link to the site — to the project FHIR channel and to any partner integrating against the IG. That is how contributors learn their FSH landed and how implementers learn something they depend on moved. Merge and tag the version when its pull request is approved.

The site is published at https://fhir.apps.health/ from the Well-Polaris/nexus-ig repository, which hosts the built output and nothing else.

Opening the next version

Open the next version as soon as the current one is published, so that work landing afterwards has somewhere to go and nothing is handed around under a released version number.

  1. Branch. From main if the previous release has merged; otherwise from the previous release branch, and rebase onto main once it merges.
  2. Open a candidate heading. set-version renames an in-flight heading and does not create one, so add ## [Unreleased] above the top dated heading in CHANGELOG.md and in the seed generator's changelog.
  3. Stamp it: npm run build <x.y.z>-candidate. The cut also rewrites the seed generator's field-mapping manifest from whatever reference corpus is on disk; that is not release content, so restore the file from the base branch.
  4. Commit, then run npm run build once more. The first build after a cut can move the generated source-content hashes; fold them into the same commit. The version is open when the gate is green and the working tree is clean.
  5. Scope it. The release ticket names the version and theme, and every change promised for it carries the release's scope label -- a change that is not labelled is invisible to release scoping.

Everything added from then on follows the artifact-id rule in conventions.md (nexus-<thing>) and writes its own changelog entry as it lands.