This wiki has undergone a migration to Confluence found Here
<meta name="googlebot" content="noindex">

Difference between revisions of "Posting the FHIR specification on hl7.org"

From HL7Wiki
Jump to navigation Jump to search
(Created page with "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 design...")
 
Line 49: Line 49:
 
** replace the url in the 'compare to version X' link (and possibly the stated version) with the correct URL
 
** 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]
 
** 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]
 +
* run the java class "org.hl7.fhir.tools.converters.WebSitePatcherForHL7IIS" on the fhir/[x] directory - this will produce .xml1, .xml2, .json1, .json2 clones of xml and json files. These are needed to support IIS mime-type redirects
 +
* ftp the content from fhir/[x] on your local directory to fhir/[x] on the server
 +
* let the community know that a new version of FHIR is available
 +
 +
== Full release steps ==
 +
 +
If you are doing a full release, then there's a whole lot of additional steps to take, to replace the existing content
 +
 +
* write a windows batch file to delete the existing spec (all files, all sub-directories that are not a past version, or an affiliate root) and then copy from [y] where [y] is a temporary directory name, and then delete [y]
 +
* organise for the HL7 webmaster to run this on the server later in the process (ensure it is marked read-only before doing that)
 +
* create a fhir/[y] directory in your local copy of the web
 +
* copy the publish content from the build to the fhir/y directory, and follow similar instructions as above. Note that the actual urls and names and releases will be a little different for this, which is the main release
 +
 +
* test the batch file in a temporary copy of the entire fhir subtree
 +
* upload from

Revision as of 04:09, 21 March 2017

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]
  • run the java class "org.hl7.fhir.tools.converters.WebSitePatcherForHL7IIS" on the fhir/[x] directory - this will produce .xml1, .xml2, .json1, .json2 clones of xml and json files. These are needed to support IIS mime-type redirects
  • ftp the content from fhir/[x] on your local directory to fhir/[x] on the server
  • let the community know that a new version of FHIR is available

Full release steps

If you are doing a full release, then there's a whole lot of additional steps to take, to replace the existing content

  • write a windows batch file to delete the existing spec (all files, all sub-directories that are not a past version, or an affiliate root) and then copy from [y] where [y] is a temporary directory name, and then delete [y]
  • organise for the HL7 webmaster to run this on the server later in the process (ensure it is marked read-only before doing that)
  • create a fhir/[y] directory in your local copy of the web
  • copy the publish content from the build to the fhir/y directory, and follow similar instructions as above. Note that the actual urls and names and releases will be a little different for this, which is the main release
  • test the batch file in a temporary copy of the entire fhir subtree
  • upload from