FHIR Package IG Release Policy Issue

Package Release Versioning

This document discusses a formal release policy for published versions of FHIR implementation guides.

Background

At present, Implementation guides are published in 2 parts: the human readable part, and the computer readable package.

The human readable part is the bit that is obvious, and that HL7 is accustomed to. This is a set of HTML files that comprise the human readable documentation for the implementation guide. This is the content that is approved by TSC, and published to the HL7 web server – typically at http://HL7.org/fhir/[realm]/[code]/[publicationId]. Publication Id is either YYYYMMM, or STU[N]. Note that when the release is a full release, it is also published to the root at http://HL7.org/fhir/[realm]/[code] as well, so that this URL contains the latest formally released version – if there is one. The TSC balloting/publication rules assign the publicationId, or it is explicitly approved by the TSC through the NIB.

Each published guide has a version assigned, which is shown in each page as the formal version of the page. All HL7 implementation guides use Semantic versioning, where the version has 3 parts: [major].[minor].[patch]. In principle, major versions are incremental whenever an incompatible change is made to the guide In general, we try to ensure that the major version matches the STU level, as this is easiest for implementer, and use the minor version to mark ballot copies, but that’s not always possible due to past choices and mismatches between the basic principles of semantic versioning and the HL7 ballot cycle. The product director assigns the version after discussion with the IG editors, keeping in mind the publicationId and the context of use of the IG.

The version is a way (one of several) for users to be precise about which release of the IG they are referring to. But it becomes important when working with the computable version of the implementation guide.

Each published implementation guide has a matching package. The package is an NPM package (an external standard for publishing reusable code libraries that we use for FHIR packages) which contains the resources that are included in the implementation guide (profiles, value sets, examples etc), and some miscellaneous other schema files that implementer may find useful. Each implementation guide is assigned a package id, which is created from the details supplied in the IG proposal approved by the FMG (e.g. hl7.fhir.us.core). This package id is fixed across the life of the IG. The package is also assigned a version, the value of which comes from the published specification it matches (also, there is the special value “current” which refers to the current build as of now).

Packages are referred to by [id]#[ver] e.g hl7.fhir.us.core#1.1.0, which uniquely identifies a particular FHIR IG either in the FHIR eco-system or the global NPM package system. Other packages and software that uses the packages can refer to them by this id.

Updating Packages

The tooling chain has been migrating to the NPM based package chain for nearly a year now. In particular, the IG publisher itself is deeply dependent on the package infratstructure now. The issue arises when updates to the NPM package are required.

Updates to the NPM package might arise for 2 different reasons:

• A technical correction is being made to the standard itself; some actual content of the standard is changing, and the package must be updated as a consequence
• Some error in the package representation has been found, and it must be updated

The first follows a well known path, but is very rare – I believe that it hasn’t yet happened with one of the FHIR IGs (though it has happened with each of the core specification releases).

The second has proven much more common. Typically, new packages for the IGs have been released when:

• Files have been found missing from the package
• The generated snapshots of the profiles in the IG are wrong
• The package identification information has been updated

Usually, these problems are diagnosed as part of a publication or code generation error in a downstream dependent NPM package, and there is considerable time pressure to release a fixed version.

Releasing a new NPM package is relatively simple: increment the version number, and post a new version to the repository. NPM packages are required to use semantic versioning – that is, major.minor.patch, so technical corrections to the specification or corrections to the package both result in changes to the patch number.

Problem

The problem is that there is presently no capacity to update the patch number when correcting the package; the version is fixed to the published version. So, for instance, when US Core is 1.1.0, the package must also be 1.1.0.

At present, we’ve been working around this by uploading a new version of the package to overwrite the previous version, and then telling users who need to the fixes to hack their local cache and remove their existing copy. This is not scalable, and requires hacked NPM package software. So this not a workable solution.

It’s not possible to add another version number e.g. major.minor.patch.packagever, since this is not allowed under NPM rules.

Solution

After discussion in FHIR-I, we propose the following solution:

• When a technical correction is made to the published specification (after TSC approves), the patch is incremented, the copy of the specification is updated, and a new package with the new patch number is released
• When a package correction is made, with no change to the specification, the patch number is incremented, it is changed in the existing published version of the specification, and a new package with the new patch number is released

This allows dependent packages to indicate a minimum version that they depend on (e.g. 1.1.2+ ensures to get any package with patch 2 or after), to ensure they get whatever fixes are needed, or to specify any version if none of the changes are relevant. Note that this solution allows for the stated patch version of the published IG to be changed without exercising the technical correction process. No changes to the IG other than the stated version are allowed under this process; any other change to the HTML will require the formal technical correction process to be used.

Additional Notes:

• Any changes to the human readable IGs are documented in the IG (this is already standing practice for the FHIR Core spec, but we've never actually made any technical corrections to IGs)
• NPM package releases - whether caused by package level fixes or full technical corrections - will be tracked in the relevant package-list.json and appear as a sub-list in the version history for the IG