- Minimize manual operation requirement
- Maximize leverage of current FHIR releases publication tools and processes
- Be able to create a new published release on demand of both the full set of HL7 Terminology, as well as product line subsets or special collections.
- Timing of a published release is ad hoc, ie not schedule by particular dates but driven by other HL7 events and needs for such a release.
The content accessed through http://terminology.hl7.org as browsable terminology is generated with the use of the FHIR IGPubliser set of tools. In order to drive this, the HL7 Terminology is actually a FHIR IG "under the covers". There are a number of special templates and control files that differ from those used for the FHIR IGs coming out of the Gravity and Accelerator projects, but the basic process and tooling is mostly the same.
Because terminology changes frequently, and experience has taught us that terminology releases happen around an order of magnitude more frequently that releases of a Standard or Implementation Guide (IG), the process will be explicitly put into a JIRA workflow in order to have predictable an controllable steps that are also amenable to ongoing automation improvement. At the current time, the Software Maintenance UTG JIRA Project ("UPSM") is planned to be the home for the release workflow. Any of the proposals (JIRA Issues) that enter this workflow will have a button which takes a curator or admin to the release workflow (away from the workflow to implement an Issue). The intent it to have a "permanent" issue for initial control of releases in the same way that we have a "permanent" issue for setting of the voting control parameters; these issues never transition out of the workflow, but are used as entry points for special control functions in the terminology maintenance.
The base process in place for publishing FHIR Implementation Guides can be found here.
JIRA workflow and operator functions
- Permanent Issue for Control of Publishing Releases
- Question: Should there be an Issue Type in the UPSM for "Published Release" and to 'kick off' the release process, a curator or admin creates a new Issue of this type and works through the steps?
- A number of custom fields to hold the information about the release are used to gather the release documentation from the curator. This includes:
- Reason for the release
- Release version
- Type of release. Types of releases are:
- Full, complete set of HL7 Terminology
- V3 only
- V2 only
- CDA only
- FHIR only
- Question: how should the releases be versioned? If a 3 part semi-semver layout is chosen, what do the clauses signify?
- A snapshot and the time of the snapshot of the current GitHUB/UTG content is taken
- A local build is triggered to construct the release
- The local build integrity and success is checked
- Operations are run to create a destination folder for the release under http://terminology.hl7.org/releases
- Operations are run to create a release manifest (List resource) which lists all of the resources in the release
- The zip file of the IG is uploaded to the newly created folder and unzipped
- Operations are performed to do all of the redirects if this is a Full release
- The installed release is spot checked that it looks OK
- Operations are run to create the new entry in the releases manifest section of the main home page
- Final check browsing to the release via http://terminology.hl7.org home page is done
- Release is finalized
Release pages at terminology.hl7.org
The initial plan is to have the releases under http://terminology.hl7.org/releases. Under that will be folders for the different types of releases, with the first one to be implemented being "full".
Inside that folder will be labeled folders, one per release. Decision is not yet made whether they should be named for the date of the release or the release ID.
For use of release IDs, there is a question as to the numbering uniqueness: for instance, will there be a 1.0.0, 1.1.0, 2.0.0 etc for the 'full' as well as for others that have at least one release? Or should the release ID hold in some way whether it is a full or partial release?
Process and Sequence
The JIRA workflow will be updated to reflect the manual workflow currently documented in the FHIR publication release process (see link above). Parts of this will be automated as time and development resources permit over the next year.
The generation of a new release also includes the generation of a Published Release Manifest, which is a LIST resource that lists all of the content items (code systems, value sets, concept maps, and naming systems) in the release. The manifest also contains the information of the tooling and publishing release process versions used to generate the release. This resource will be in the full downloads package. Still TBD: should this also be rendered on the release documentation pages?
Open Items that must be addressed (differences from the FHIR release process)
- Specification of the destination end point location (URL server location) for the 'official' release
- Addition of the coremif generation into the process so that it happens during the release and is deposited in the appropriate location for download
- Redirects to accomplish the correct endpoints when the canonical URL is clicked on
- Download package(s) for loading/updating servers in the world
Versioning of Releases
The Terminology Releases will use a 3 part version ID. Each part is an integer. The parts are Major.Minor.Patch
The version numbers of the ci build and the releases follow the same scheme
- Major Version Number
- Beginning number is 1
- Pre-release initial debugging is major number 0
- Incremented when a new Published Release is done, with a checkpointed snapshot of the GiHub trunk ('master') of the HL7 Terminology to make a published full release
- Incrementing sets the minor number back to 0
- Incrementing sets the patch number back to 0
- The release manifest carries the last ci build version number from which the release was snapshotted
- Minor Version Number
- Beginning number is 0
- Incremented when singificant updates, changes, or enhancements to content (code systems, value sets, naming systems, concept maps) is PUSH'd to the GitHub trunk ('master') content source of truth
- Incremented number resets the Patch Number (see next item) to zero
- Patch Version Number
- Beginning number is 0
- Incremented every time there is a commit and push to the GitHub trunk ('master' of the terminology source of truth) subsequent to a Minor Number increment