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

Difference between revisions of "FHIR IG QA process"

From HL7Wiki
Jump to navigation Jump to search
(migrate to Confluence and add links)
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
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:
 
Check list for publishing an IG:
  
Line 5: Line 8:
 
You must know, at all times, 3 things:
 
You must know, at all times, 3 things:
  
* The [wiki url] for the wiki page that documents the IG approval
+
*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
+
*[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
+
*[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 =
+
=When the NIB is submitted=
  
* The [[:category:FHIR_IG_Proposal|IG Proposal]]  must have been approved by FMG
+
*The [[:category:FHIR_IG_Proposal|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
+
*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 =
+
=Before Ballot Announcement=
  
 
These checks must be carried out before the ballot annoucement is made, and you must verify with the ballot coordinator (Lynn)
 
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
 
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 [[https://github.com/hl7-fhir/auto-ig-builder/blob/master/README.md 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 be [[https://github.com/hl7-fhir/auto-ig-builder/blob/master/README.md 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 canonical URL of http://hl7.org/fhir/[realm]/[code]
* The IG must have a package name of hl7.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
+
*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)
+
*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
+
*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)
 
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 =
+
=For publication=
  
 
Before the specified FMG deadline for submission of IG Content, do the following checks:
 
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 canonical URL of http://hl7.org/fhir/[realm]/[code]
* The IG must have a package name of hl7.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)
+
*The IG must use the standard HL7 FHIR IG template (or must be exempted by FMG)
* The IG must be auto-building successfully on the CI build system with few / no errors (see below)
+
**Tight timelines will not be accepted as a rationale, so best to start using the IG template early...
* 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 IG must be auto-building successfully on the CI build system with few / no errors (see below)
** the best way to ensure this is to use the fixed-business-version parameter
+
*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 ballot status (e.g. STU1 Ballot 2) must be explicitly stated on the page header and/or footer  
+
**the best way to ensure this is to use the fixed-business-version parameter
* All IG dependencies and core version reference must be literal versions, not the special values 'current' or 'dev'
+
*The ballot status (e.g. STU1 Ballot 2) must be explicitly stated on the page header and/or footer
* 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
+
*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 ==
+
==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 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.  
Line 48: Line 52:
  
 
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.  
 
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 may not allow the IG to go to ballot.
+
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 =
+
=Publishing process=
  
 
This is the process for publishing the final implementation guides as followed by the FHIR Product Director
 
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:
+
*Create a Google worksheet to track the process of the IGs being published - links below. Start by entering the following:
** Realm
+
**Realm
** Code
+
**Code
** GitHub source URL
+
**GitHub source URL
** Final web page destination (version specific)
+
**Final web page destination (version specific)
** Package ID
+
**Package ID
** Version of FHIR it is based on
+
**Version of FHIR it is based on
** Version of IG itself
+
**Version of IG itself
** dependencies and versions
+
**dependencies and versions
** Editor contacts
+
**Editor contacts
* Check that all the publication checks in the previous sections have been made
+
*Check that all the publication checks in the previous sections have been made
* Check that history notes are available
+
*Check that history notes are available
* Check that the guide builds ok, and review errors with editor
+
*Check that the guide builds ok, and review errors with editor
* Do a build, and check for unexpected terminology errors in qa.html
+
*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
+
*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:
+
*Edit the templates for the IG:
** Ensure that the title+ header reflect the ballot/publication status
+
**Ensure that the title+ header reflect the ballot/publication status
** Add a head status bar using html like below
+
**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)
+
**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
+
*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)
+
*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
+
*Copy output into correct location on the local copy of the FHIR website
* Update the history.html for the new version
+
*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)
+
*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
+
*Verify on the server that all the links are correct
* Ask for editors to review
+
*Ask for editors to review
  
== Record of IG publication processes ==
+
==Record of IG publication processes==
  
* 2018Sep ballot: [[https://docs.google.com/spreadsheets/d/1eW02t08RMECLKFf697jPzZyHfYxz2TqW6IQB5QpqcNI/edit?usp=sharing Sheet]]
+
*2018Sep ballot: [[https://docs.google.com/spreadsheets/d/1eW02t08RMECLKFf697jPzZyHfYxz2TqW6IQB5QpqcNI/edit?usp=sharing Sheet]]
* QI-Core final publication: [[https://docs.google.com/spreadsheets/d/12MDV2jP9lm91HrRDdZYbX5lV9B492v2q4wkFiEgW9sE/edit?usp=sharing Sheet]]
+
*QI-Core final publication: [[https://docs.google.com/spreadsheets/d/12MDV2jP9lm91HrRDdZYbX5lV9B492v2q4wkFiEgW9sE/edit?usp=sharing Sheet]]
 +
*2018 Sep balot #2: [[https://docs.google.com/spreadsheets/d/1q70iPSEz0zgm3CfmKsxnW5z2Ei0Vr6m_9hW0tbR_I8E/edit?usp=sharing Sheet]]

Latest revision as of 15:48, 8 November 2019

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]