Posting the FHIR specification on hl7.org

This page provides rough documentation on the overall process for posting the FHIR specification to hl7.org/fhir.

This process is used by the FHIR product director (or designated agent) when a new version of the FHIR specification is posted.

Things to consider prior to planning this process

Before planning this process, the following things must be considered, and the plan that leads to posting a new version of FHIR must allow for them:

• Typically, stable versions are posted 6-8 weeks prior to an HL7 meeting for a connectathon, and offr supporting ballot, if applicable. Full releases mostly at other times
• Whenever a new version is posted, the process must be co-ordinated with the reference implementation maintainers (at least James Agnew, Brian Postlethwaite, Pascal Piffner, Nicola Rhyzikov) in advance
• FMG must sign off on a QA plan to ensure that the posted release represents a stable consensus from the committers that represent different domains
• There must be a freeze process and a technical QA prior to the build to ensure that the build and the terminology reference server are in sync
• For full releases, the TSC must ok the publication - make sure this is part of the process, and the interaction between the TSC and the build is well understood

The actual process

Once the build is stable, and FMG have signed off on it's state and the technical build tools are all aligned, start the actual build.

Phase 1: The build process

• upgrade the version (see fhir.ini). Rebuild following the instructions in fhir.ini. Then commit to svn
• then, upgrade the terminology server to the new version, and upgrade the active terminology server (e.g. tx.fhir.org)
• delete the vscache contents (build/vscache), and run the build again. (slow - hours). Check for new errors cropping up. Then commit again

Note: this is the content that TSC approves from publication. From the time it is submitted to TSC, it is frozen until approved.

• delete the contents of the publish directory
• now, start the build again, but this time with the parameter -web (check)
• check the output for (new) errors

Phase 2: post-processing

What is on build.fhir.org is the final copy, and cannot be altered without invoking the TSC technical correction process, except in 3 regards

• The version information (titles, product names, versions) in the header and footer can be changed by the Product Director
• A pink or gold box can be added to the page immediately above the header that describes how the page / specification fits into the overall version release of the FHIR product versions
• URLs for links and images can be rebased for moving from one location to another (i.e. from http://build.fhir.org to hl7.org/fhir/...), and external URLs can be fixed

This is the rough process for moving the content to the web. In order to use this process, you need an existing directory that contains the same content as the /fhir directory on the HL7 web server, and ftp access to that directory.

• copy the generated output from publish (from the run with the -web parameter) to fhir/[X] where X is the destination directory.
• tag the build to /tags/[X] so that there is a branch in which the release can be maintained as necessary
• increment the version number in trunk, following the fhir.ini process, so implementers can tell them apart (note: this step can delayed until there is change in the trunk)
• if this a full release, then the value of [x] is... don't know (as "STU"N, but not next time). TBA...
• Otherwise the value of [X] is YYYYMmm where YYYY is the year and MMM is the month (e.g. Sep) of the official ballot cycle. Note that this is the month *after* you actually publish
• now, using a text editor, do search and replace on the HTML files. For each search/replace, check that the number of replaces is as expected
  • replace the title in the header (e.g. "Current build") with the correct title
  • replace the stated version in the footer (e.g. "STU3 Candidate (v3.0.0-11828)") with the correct version for publication. The technical version must be correct, including the build number
  • replace the url in the 'compare to version X' link (and possibly the stated version) with the correct URL
  • search for references to build.fhir.org in the spec, and.. resolve.... them (good luck with this; a few are legimately for the current build, but most are not, and need to be changed to either hl7.org/fhir or hl7.org/fhir/[X]