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.
- Bring in
main.git fetchand mergeorigin/maininto 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. - 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. - Run the gate:
npm run build. Contributor branches cannot regenerate the shared surface, so expect to commit regenerated output here. Check: green, andgit statusclean. - Run the library suite:
npm run test.publishruns 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. - 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. - 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.
- Cut it:
npm run build <x.y.z>, no-candidate. Check: green, the changelog heading is dated today, andgit statusis clean after committing. - Publish:
npm run publish -- --dry-run, thennpm run publish(add-- --with-publisherif a^copyrightchanged). It is a release to app partners; the owner confirms before the push. Run every command from step 3 on withGITHUB_BASE_REF=mainset. 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 withmainreports every application changemainbrought in as its own reach. Check: the live site, not the local build:/,/package.tgzand/packages/nexus-<x.y.z>.tgzanswer 200, and the home page reads the new version. - 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. - 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.yamlsaysstatus: 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:leavesdraftthe 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.
- Branch. From
mainif the previous release has merged; otherwise from the previous release branch, and rebase ontomainonce it merges. - Open a candidate heading.
set-versionrenames an in-flight heading and does not create one, so add## [Unreleased]above the top dated heading inCHANGELOG.mdand in the seed generator's changelog. - 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. - Commit, then run
npm run buildonce 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. - 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.