FHIR IG QA process

Content of this page has been migrated to Confluence here: https://confluence.hl7.org/display/FHIR/FHIR+IG+QA+process

Check list for publishing an IG:

this is the checklist for publishing an implementation guide for ballot by HL7.

You must know, at all times, 3 things:

• The [wiki url] for the wiki page that documents the IG approval
• [realm] - the realm code that is assigned to the IG (e.g., uv or us) - as documented on the wiki page
• [code] - the code that is assigned to the IG (e.g., core or adv-thing - as documented on the wiki page

When the NIB is submitted

• The IG Proposal must have been approved by FMG. (This means the submission should have been sent to the FMG at least 2 Wednesdays before NIB deadline to allow time for review and resubmission if necessary.)
• Check that realm listed on the NIB agrees with the realm as documented in the [wiki url] and the PSS, or else agrees with a variation that has been approved by FMG

Before Ballot Announcement

These checks must be carried out before the ballot annoucement is made, and you must verify with the ballot coordinator (Lynn) that you have met these goals. They must be carried out by whoever is nominated as the contact on the NiB

• The IG must be [auto-building] successfully on the CI build system (see IG Publisher Documentation) Note: it may be incomplete or have many errors at this point
• The IG must have a canonical URL of http://hl7.org/fhir/[realm]/[code]
• The IG must have a package name of hl7.fhir.[realm].[code]
• You must have decided what the version number will be, following the normal version numbering policy, and have secured the agreement of the FHIR Product Director
• The IG must use the standard HL7 FHIR IG template (or must be exempted by FMG)
• Check that the ballot announcement has the correct details for the IG, including getting the realm correct

If, for any reason, it is necessary to seek a variance from any of these procedures, the request must be approved by the FHIR product director on a case-by-case basis (noted on the IG approval page)

For publication

Before the specified FMG deadline for submission of IG Content, do the following checks:

• The IG must have a canonical URL of http://hl7.org/fhir/[realm]/[code]
• The IG must have a package name of hl7.fhir.[realm].[code]
• The IG must use the standard HL7 FHIR IG template (or must be exempted by FMG)
  • Tight timelines will not be accepted as a rationale, so best to start using the IG template early...
• The IG must be auto-building successfully on the CI build system with few / no errors (see below)
• The agreed version number (see above) must be specified in all the conformance resources, and in the build control file as the version for the IG, and must appear as the specified version in the page header and/or footer
  • the best way to ensure this is to use the fixed-business-version parameter
• The ballot status (e.g. STU1 Ballot 2) must be explicitly stated on the page header and/or footer
• All IG dependencies and core version reference must be literal versions, not the special values 'current' or 'dev'
• A set of history notes documenting the significant changes must be prepared. These may be in the IG, or in a separate document for the FHIR Product director to publish

Errors

The IG publisher reports many errors in the file qa.html. This will will be published so that any reviewer of the specification can check the status of the IG. The FHIR Product Director will review the QA page before publishing, and discuss outstanding issues with the editors before publishing.

Implementation Guides can be (and have been) published with outstanding errors, either due to deficiencies in the tooling, or lack of time or authority on the part of the editors. The FHIR Product Director works with FMG to set allowable parameters for such errors. If there are too many unresolved errors, FMG might not allow the IG to go to ballot and/or to be published until errors are resolved.

Publishing process

This is the process for publishing the final implementation guides as followed by the FHIR Product Director

• Create a Google worksheet to track the process of the IGs being published - links below. Start by entering the following:
  • Realm
  • Code
  • GitHub source URL
  • Final web page destination (version specific)
  • Package ID
  • Version of FHIR it is based on
  • Version of IG itself
  • dependencies and versions
  • Editor contacts
• Check that all the publication checks in the previous sections have been made
• Check that history notes are available
• Check that the guide builds ok, and review errors with editor
• Do a build, and check for unexpected terminology errors in qa.html
• Check that there are no references to build.fhir.org and fix/repeat previous step until there are none
• Edit the templates for the IG:
  • Ensure that the title+ header reflect the ballot/publication status
  • Add a head status bar using html like below
  • Ensure that the footer has the right content and links - in particular, history links to the cross version history page ([canonical]/history.html)
• Build again, and repeat previous step until all pages are correct
• Final build with -publish [url], using the url from above (IG will be the same, but package will be production package, not current)
• Copy output into correct location on the local copy of the FHIR website
• Update the history.html for the new version
• Upload the new content + history.html to the hl7.org server (or fhir.org, if FHIR foundation content)
• Verify on the server that all the links are correct
• Ask for editors to review

Record of IG publication processes

• 2018Sep ballot: [Sheet]
• QI-Core final publication: [Sheet]
• 2018 Sep balot #2: [Sheet]