Difference between revisions of "Process for Publishing a FHIR IG"

From HL7Wiki
Jump to navigation Jump to search
(migrate to Confluence and add links)
 
(27 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= Publishing a FHIR IG =
+
Content for this page has been migrated to Confluence here: https://confluence.hl7.org/display/FHIR/Process+for+Publishing+a+FHIR+IG
 +
 
 +
=Publishing a FHIR IG=
  
 
This process is followed by anyone when publishing a FHIR IG to http://hl7.org/fhir/  
 
This process is followed by anyone when publishing a FHIR IG to http://hl7.org/fhir/  
  
= Pre-conditions =
+
=Pre-conditions=
  
 
To follow this process, you must have:
 
To follow this process, you must have:
* permission from the FHIR Product Director to publish FHIR IGs (including write access to the google sheet)
 
* permission from FMG+TSC to publish the particular FHIR IGs
 
* an FTP acccount with access to the source for http://hl7.org/fhir
 
  
You must also know how to run the IGPublisher locally
+
*permission from the FHIR Product Director to publish FHIR IGs (including write access to the [[https://docs.google.com/spreadsheets/d/1SRxxwA5GSJNx93oXUNTSPqbL19yeBYrNCCQAZ0sp0CI/edit#gid=0 FHIR IG Publication Record]])
 +
*permission from FMG+TSC to publish the particular FHIR IGs
 +
*an FTP acccount with access to the source for http://hl7.org/fhir
 +
*permission to push changes to https://github.com/FHIR/ig-registry
 +
*A local clone of the FHIR IG registry github repository https://github.com/FHIR/ig-registry to {registry}
 +
*A local clone of the FHIR History Template github repository https://github.com/HL7/fhir-ig-history-template to {history}
  
= Record Keeping =
+
You must also know how to run the IGPublisher locally
 +
 
 +
=Record Keeping=
  
 
All publication runs must be recorded in the [[https://docs.google.com/spreadsheets/d/1SRxxwA5GSJNx93oXUNTSPqbL19yeBYrNCCQAZ0sp0CI/edit#gid=0 FHIR IG Publication Record]]
 
All publication runs must be recorded in the [[https://docs.google.com/spreadsheets/d/1SRxxwA5GSJNx93oXUNTSPqbL19yeBYrNCCQAZ0sp0CI/edit#gid=0 FHIR IG Publication Record]]
Line 18: Line 24:
 
When you being processing the publication request, create a new row in the sheet, and add the following columns:
 
When you being processing the publication request, create a new row in the sheet, and add the following columns:
  
* Operator : Your name
+
*Operator : Your name
* IG Name : The formal name for the ballot or publication request  
+
*IG Name : The formal name for the ballot or publication request
* IG Source : The github repository URL where the source is located - Check that the repository URL is HL7 (or an other wise approved Organization - consult CTO for approved list)
+
*IG Source : The github repository URL where the source is located - Check that the repository URL is HL7 (or an other wise approved Organization - consult CTO for approved list)
* Primary Editor : the name of the editor who will handle any QA issues  
+
*Primary Editor : the name of the editor who will handle any QA issues
* IG approval: The URL of the wiki page that FMG Approved for the proposal of the IG (if there isn't one, consult the FHIR product director and put "(n/a)")
+
*IG approval: The URL of the wiki page that FMG Approved for the proposal of the IG (if there isn't one, consult the FHIR product director and put "(n/a)")
* new IG : "yes" if this is the first time that any version is being published for this IG (whatever version - draft or ballot)
+
*new IG : "yes" if this is the first time that any version is being published for this IG (whatever version - draft or ballot)
* TSC Approval:  
+
*TSC Approval:  
** if this is a milestone release (e.g. not for ballot) check that TSC has signed off on the publication, and record a link to the TSC task in the spreadsheet
+
**if this is a milestone release (e.g. not for ballot) check that TSC has signed off on the publication, and record a link to the TSC task in the spreadsheet
** if this is for ballot, write "ballot YYYYMMM"
+
**if this is for ballot, write "ballot YYYYMMM"
  
= Checks =
+
=Checks=
  
 
The following checks must be run:
 
The following checks must be run:
  
* Realm: add the realm code identified in the IG approval page. Check that this is consistent with the stated scope of the ballot and in the TSC approval
+
*Realm: add the realm code identified in the IG approval page. Check that this is consistent with the stated scope of the ballot and in the TSC approval
* Code: add the code as identified in the IG Approval page (note that the name of the github repository does not need to be the same)
+
*Code: add the code as identified in the IG Approval page (note that the name of the github repository does not need to be the same)
* fill out the canonical (http://hl7.org/fhir/{realm}/{code}) and packageId (hl7.fhir.{realm}.{code}) values.  
+
*fill out the canonical (http://hl7.org/fhir/{realm}/{code}) and packageId (hl7.fhir.{realm}.{code}) values.  
** If this is is a new IG: Look up the URL {canonical}/package-list.json and check that it doesn't exist
+
**If this is is a new IG: Look up the URL {canonical}/package-list.json and check that it doesn't exist
** if this is not a new IG: Look up the URL {canonical}/package-list.json and check that the canonical url and packageId and the name of the IG in the package list agree with the details for the IG (canonical and packageId must be identical, name can vary a little).  
+
**if this is not a new IG: Look up the URL {canonical}/package-list.json and check that the canonical url and packageId and the name of the IG in the package list agree with the details for the IG (canonical and packageId must be identical, name can vary a little). Also check that there are no single quotes in the description; use ASCII equivalent "'" instead.
* Find the IG (based on it's github URL org and name) in https://hl7-fhir.github.io/auto-ig-builder/builds.html, and check that the IG was built in the last 24 hours. If not, rebuild it. Wait for it to rebuild (refresh the page, or watch https://chat.fhir.org/#narrow/stream/179297-committers.2Fnotification)
+
*Find the IG (based on it's github URL org and name) in https://fhir.github.io/auto-ig-builder/builds.html, and check that the IG was built in the last 24 hours. If not, rebuild it. Wait for it to rebuild (refresh the page, or watch https://chat.fhir.org/#narrow/stream/179297-committers.2Fnotification)
* now check the qa page (rightmost link on the IG Builds page).  
+
*now check the qa page (rightmost link on the IG Builds page).  
** check that the packageId and canonical URL in the first line are correct against the spreadsheet, and check that the stated path starts with {canonical}
+
**check that the packageId and canonical URL in the first line are correct against the spreadsheet, and check that the stated path starts with {canonical}
** Review any errors in the page, paying particular attention the publication QA checks at the top
+
**Review any errors in the page, paying particular attention the publication QA checks at the top
** If there are any errors, refer to the FHIR product Director for approval
+
**If there are any errors, refer to the FHIR product Director for approval
** Once ok, record "yes (N)" in Build QA column, where N is the number of errors
+
**Once ok, record "yes (N)" in Build QA column, where N is the number of errors
* in the version column, record the version as stated in the first line (after the {packageId#} part
+
*in the version column, record the version as stated in the first line (after the {packageId#} part
** if this is a new IG: the version should be 0.1.0, or as approved by the FHIR Product Director
+
**if this is a new IG: the version should be 0.1.0, or as approved by the FHIR Product Director
** if this is a not a new IG: check that the FHIR Product Director has approved the version
+
**if this is a not a new IG: check that the FHIR Product Director has approved the version
* in the subdir column, record the subfolder stated in the publication path
+
*in the subdir column, record the subfolder stated in the publication path (in the current entry in the package-list.json file)
** If it does not conform to the pattern YYYYMMM (with the date correct) or STU{X}, check with the FHIR product director
+
**project team needs to add a new entry if one does not exist since the last ballot
* Now review the actual guide (left most link in the IG build page)  
+
**If it does not conform to the pattern YYYYMMM (with the date correct) or STU{X}, check with the FHIR product director
* Check that the header conforms to the [[FHIR Implementation Guide Publishing Requirements]]:
+
*Now review the actual guide (left most link in the IG build page)
** check that the header shows the name of the IG and the ballot status correctly.  
+
*Check that the header conforms to the [[FHIR Implementation Guide Publishing Requirements]]:
** check that the header shows the correct HL7 logo
+
**check that the header shows the name of the IG and the ballot status correctly.
** check that the header includes the yellow publish box that displays correctly (don't worry about what it actually says)
+
**check that the header shows the correct HL7 logo
** if all checks out, "yes" in the header column
+
**check that the header includes the yellow publish box that displays correctly (don't worry about what it actually says)
* Check that the footer conforms to the [[FHIR Implementation Guide Publishing Requirements]]:
+
**if all checks out, "yes" in the header column
** check that the following items are shown in the footer: packageId, version, FHIR version, publishing committee, history link, propose changes link, Copyright (© 20YY+), generated date
+
*Check that the footer conforms to the [[FHIR Implementation Guide Publishing Requirements]]:
** if all checks out, "yes" in the footer column
+
**check that the following items are shown in the footer: packageId, version, FHIR version, publishing committee, history link, propose changes link, Copyright (© 20YY+), generated date
 +
**if all checks out, "yes" in the footer column
 +
*check that {registry} and {history} are up to date (git PULL)
  
= Local Build =
+
=Local Build=
  
 
Now that the main checks have been done, you need to do a local build. To do that, you need a copy of the IG Publisher - see [[IG Publisher Documentation]] for assistance
 
Now that the main checks have been done, you need to do a local build. To do that, you need a copy of the IG Publisher - see [[IG Publisher Documentation]] for assistance
  
* clone the github repository to your local drive = {clone}
+
*clone the github repository to your local drive = {clone}
** you should call it {packageId}#{version}
+
**you should call it {packageId}#{version}
* run the IG publisher, clearing the terminology cache (run the org.hl7.fhir.igpublisher.jar -ig {clone} -resetTx -web)
+
*run the IG publisher, clearing the terminology cache (run the org.hl7.fhir.igpublisher.jar -ig {clone} -resetTx -web)
* check that the local {clone}/output/qa.html file matches the CI build qa.html  
+
*check that the local {clone}/output/qa.html file matches the CI build qa.html  
** troubleshooting on https://chat.fhir.org/#narrow/stream/179165-committers  
+
**troubleshooting on https://chat.fhir.org/#narrow/stream/179165-committers
** once it matches, "yes" in the local qa column
+
**once it matches, "yes" in the local qa column
* Zip up the folder {clone} as it is to a file named {packageId}#{version}.zip and ftp to ftp://hl7.org/fhir/ig-build-zips
+
*Zip up the folder {clone} as it is to a file named {packageId}#{version}.zip and ftp to ftp://hl7.org/fhir/ig-build-zips
 +
 
 
You are now good to publish the IG
 
You are now good to publish the IG
  
= Publishing the IG =
+
*check that the {clone}/output does not contain a file named package-list.json
 +
 
 +
=Publishing the IG=
  
* create a local directory = {root}
+
Note: if you are publishing a set of IGs, you can do this part of the process - and all that follows as a batch
* use FTP to copy the current contents of the uv and us sub-folders of ftp://hl7.org/fhir to {root}
 
** 150k+ files. you always need both uv and us since they are intertwined
 
* in your local directory
 
** if this is a new IG: create the folder {root}/{realm}/{code}, and copy in {clone}/package-list.json (e.g. to {root}/{realm}/{code}/package-list.json)
 
** if this is not a new IG: edit the file {root}/{realm}/{code}/package-list.json and add the entry for the {version} found in {clone}/package-list.json
 
* set the date in {root}/{realm}/{code}/package-list.json entry for {version} to today's (US) date using the format yyyy-mm-dd
 
** if this is a new IG: copy the contents of the github repository https://github.com/HL7/fhir-ig-history-template into {root}/{realm}/{code} (except for the readme.md file), and edit the name in index.html (replace 'XXXXXX')
 
* create the folder {root}/{realm}/{code}/{subdir}
 
* copy the content from {clone}/output to {root}/{realm}/{code}/{subdir}
 
* mark "yes" in the Copied column
 
  
Note: if you are publishing a set of IGs, you can do this part of the process as a batch
+
*create a local directory = {root}
 +
*use FTP to copy the current contents of ftp://hl7.org/fhir to {root}
 +
**1 million+ files. Keep this maintained in advance, or give 48 hours + to build it
 +
**Check with other publishers before making the copy (publishers = Grahame & Lynn)
 +
**If you keep this maintained, use FTP to sync your copy each time the contents of <nowiki>http://hl7.org/fhir/package-feed.xml</nowiki> changes (subscribe with a feed reader), or as discussed between publishers
 +
*in your local directory
 +
**if this is a new IG: create the folder {root}/{realm}/{code}, and copy in {clone}/package-list.json (e.g. to {root}/{realm}/{code}/package-list.json)
 +
**if this is not a new IG: edit the file {root}/{realm}/{code}/package-list.json and add the entry for the {version} found in {clone}/package-list.json
 +
*set the date in {root}/{realm}/{code}/package-list.json entry for {version} to today's (US) date using the format yyyy-mm-dd
 +
**if this is a new IG: copy the contents of {history} into {root}/{realm}/{code} (except for the readme.md file), and edit the name in index.html (replace 'XXXXXX')
 +
*create the folder {root}/{realm}/{code}/{subdir}
 +
*copy the content from {clone}/output to {root}/{realm}/{code}/{subdir}
 +
*mark "yes" in the Copied column
  
= Milestone releases =
+
=Milestone releases=
  
 
If you are doing a mile stone release (a STU publication of the IG), some additional steps are required:
 
If you are doing a mile stone release (a STU publication of the IG), some additional steps are required:
  
* delete all files and directories in {root}/{realm}/{code}, except:
+
*delete all files and directories in {root}/{realm}/{code}: org.hl7.fhir.publisher.jar -delete-current {root}/{realm}/{code} -history {history}
** any previous version directories
+
*re-run the IG publisher: org.hl7.fhir.igpublisher.jar -ig {clone} -web -milestone)
** package-list.json
+
**check it succeeds
** any files from https://github.com/HL7/fhir-ig-history-template
+
*copy the content from {clone}/output to {root}/{realm}/{code}. Say "yes" to overwrite any existing files
** be careful! - this is the trickiest part of the whole process, and there are no tools to help
+
*update the package-list.json to set "current": true on the new version, and remove that from any other past published version (but not from the current build entry)
* re-run the IG publisher: org.hl7.fhir.igpublisher.jar -ig {clone} -web -milestone)
+
*mark "yes" in the Milestone column
** check it succeeds
+
 
* copy the content from {clone}/output to {root}/{realm}/{code}  
+
=Finishing the Publication Process=
** check any 'file already exists' errors, and discuss with FHIR product Director
+
 
* mark "yes" in the Milestone column
+
*run the IGPublisher on {root}: org.hl7.fhir.publisher.jar -publish-update {root}
  
* also, make a new entry or update the entry in the file https://github.com/FHIR/ig-registry/blob/master/fhir-ig-list.json for the IG (and fill in the "register IG" column with "yes")
+
*check the output: it should report that it changed N files for each published version of the IG (including previously published versions)
 +
**if problems, consult FHIR product director (and start again from the creating a local root directory)
 +
*if you are doing a milestone release: use FTP to delete the contents of ftp://hl7.org/fhir/{realm}/{code}: yes, delete all the files
 +
*use FTP to copy the entire contents of {root}/{realm}/{code} to ftp://hl7.org/fhir/{realm}/{code} - no need to upload files that have not changed
 +
*mark "yes" in the FTPed column
 +
*commit and push the changes to the FHIR IG registry to github & mark "yes" in the Register IG column
 +
*if this is a milestone publication, let Lloyd know that it's time to mark applied tasks as published, and considered for future use tasks as open
 +
*if this is a milestone publication (not for ballots) make an announcement on the https://chat.fhir.org/#narrow/stream/179240-Announcements/topic/FHIR.20Publication.20Announcement topic in Zulip using the following template:
  
= Finishing the Publication Process =
+
  new Publication: [publication name] of the [IG Name] implementation guide: {canonical}/{subdir}
  
* run the IGPublisher on {root}: org.hl7.fhir.igpublisher.jar -publish-update {root} -url http://hl7.org/fhir -package {packageId}
+
e.g. New Publication: STU Update 3.2 of the QI-Core implementation guide: http://hl7.org/fhir/us/qicore/STU32/
* check the output: it should report that it changed N files for each published version of the IG (including previously published versions)
 
** if problems, consult FHIR product director (and start again from the creating a local root directory)
 
* use FTP to copy the entire contents of {root}/{realm}/{code} to ftp://hl7.org/fhir/{realm}/{code} - no need to upload files that have not changed
 
* mark "yes" in the FTPed column
 

Latest revision as of 15:49, 8 November 2019

Content for this page has been migrated to Confluence here: https://confluence.hl7.org/display/FHIR/Process+for+Publishing+a+FHIR+IG

Publishing a FHIR IG

This process is followed by anyone when publishing a FHIR IG to http://hl7.org/fhir/

Pre-conditions

To follow this process, you must have:

You must also know how to run the IGPublisher locally

Record Keeping

All publication runs must be recorded in the [FHIR IG Publication Record]

When you being processing the publication request, create a new row in the sheet, and add the following columns:

  • Operator : Your name
  • IG Name : The formal name for the ballot or publication request
  • IG Source : The github repository URL where the source is located - Check that the repository URL is HL7 (or an other wise approved Organization - consult CTO for approved list)
  • Primary Editor : the name of the editor who will handle any QA issues
  • IG approval: The URL of the wiki page that FMG Approved for the proposal of the IG (if there isn't one, consult the FHIR product director and put "(n/a)")
  • new IG : "yes" if this is the first time that any version is being published for this IG (whatever version - draft or ballot)
  • TSC Approval:
    • if this is a milestone release (e.g. not for ballot) check that TSC has signed off on the publication, and record a link to the TSC task in the spreadsheet
    • if this is for ballot, write "ballot YYYYMMM"

Checks

The following checks must be run:

  • Realm: add the realm code identified in the IG approval page. Check that this is consistent with the stated scope of the ballot and in the TSC approval
  • Code: add the code as identified in the IG Approval page (note that the name of the github repository does not need to be the same)
  • fill out the canonical (http://hl7.org/fhir/{realm}/{code}) and packageId (hl7.fhir.{realm}.{code}) values.
    • If this is is a new IG: Look up the URL {canonical}/package-list.json and check that it doesn't exist
    • if this is not a new IG: Look up the URL {canonical}/package-list.json and check that the canonical url and packageId and the name of the IG in the package list agree with the details for the IG (canonical and packageId must be identical, name can vary a little). Also check that there are no single quotes in the description; use ASCII equivalent "&#39;" instead.
  • Find the IG (based on it's github URL org and name) in https://fhir.github.io/auto-ig-builder/builds.html, and check that the IG was built in the last 24 hours. If not, rebuild it. Wait for it to rebuild (refresh the page, or watch https://chat.fhir.org/#narrow/stream/179297-committers.2Fnotification)
  • now check the qa page (rightmost link on the IG Builds page).
    • check that the packageId and canonical URL in the first line are correct against the spreadsheet, and check that the stated path starts with {canonical}
    • Review any errors in the page, paying particular attention the publication QA checks at the top
    • If there are any errors, refer to the FHIR product Director for approval
    • Once ok, record "yes (N)" in Build QA column, where N is the number of errors
  • in the version column, record the version as stated in the first line (after the {packageId#} part
    • if this is a new IG: the version should be 0.1.0, or as approved by the FHIR Product Director
    • if this is a not a new IG: check that the FHIR Product Director has approved the version
  • in the subdir column, record the subfolder stated in the publication path (in the current entry in the package-list.json file)
    • project team needs to add a new entry if one does not exist since the last ballot
    • If it does not conform to the pattern YYYYMMM (with the date correct) or STU{X}, check with the FHIR product director
  • Now review the actual guide (left most link in the IG build page)
  • Check that the header conforms to the FHIR Implementation Guide Publishing Requirements:
    • check that the header shows the name of the IG and the ballot status correctly.
    • check that the header shows the correct HL7 logo
    • check that the header includes the yellow publish box that displays correctly (don't worry about what it actually says)
    • if all checks out, "yes" in the header column
  • Check that the footer conforms to the FHIR Implementation Guide Publishing Requirements:
    • check that the following items are shown in the footer: packageId, version, FHIR version, publishing committee, history link, propose changes link, Copyright (© 20YY+), generated date
    • if all checks out, "yes" in the footer column
  • check that {registry} and {history} are up to date (git PULL)

Local Build

Now that the main checks have been done, you need to do a local build. To do that, you need a copy of the IG Publisher - see IG Publisher Documentation for assistance

  • clone the github repository to your local drive = {clone}
    • you should call it {packageId}#{version}
  • run the IG publisher, clearing the terminology cache (run the org.hl7.fhir.igpublisher.jar -ig {clone} -resetTx -web)
  • check that the local {clone}/output/qa.html file matches the CI build qa.html
  • Zip up the folder {clone} as it is to a file named {packageId}#{version}.zip and ftp to ftp://hl7.org/fhir/ig-build-zips

You are now good to publish the IG

  • check that the {clone}/output does not contain a file named package-list.json

Publishing the IG

Note: if you are publishing a set of IGs, you can do this part of the process - and all that follows as a batch

  • create a local directory = {root}
  • use FTP to copy the current contents of ftp://hl7.org/fhir to {root}
    • 1 million+ files. Keep this maintained in advance, or give 48 hours + to build it
    • Check with other publishers before making the copy (publishers = Grahame & Lynn)
    • If you keep this maintained, use FTP to sync your copy each time the contents of http://hl7.org/fhir/package-feed.xml changes (subscribe with a feed reader), or as discussed between publishers
  • in your local directory
    • if this is a new IG: create the folder {root}/{realm}/{code}, and copy in {clone}/package-list.json (e.g. to {root}/{realm}/{code}/package-list.json)
    • if this is not a new IG: edit the file {root}/{realm}/{code}/package-list.json and add the entry for the {version} found in {clone}/package-list.json
  • set the date in {root}/{realm}/{code}/package-list.json entry for {version} to today's (US) date using the format yyyy-mm-dd
    • if this is a new IG: copy the contents of {history} into {root}/{realm}/{code} (except for the readme.md file), and edit the name in index.html (replace 'XXXXXX')
  • create the folder {root}/{realm}/{code}/{subdir}
  • copy the content from {clone}/output to {root}/{realm}/{code}/{subdir}
  • mark "yes" in the Copied column

Milestone releases

If you are doing a mile stone release (a STU publication of the IG), some additional steps are required:

  • delete all files and directories in {root}/{realm}/{code}: org.hl7.fhir.publisher.jar -delete-current {root}/{realm}/{code} -history {history}
  • re-run the IG publisher: org.hl7.fhir.igpublisher.jar -ig {clone} -web -milestone)
    • check it succeeds
  • copy the content from {clone}/output to {root}/{realm}/{code}. Say "yes" to overwrite any existing files
  • update the package-list.json to set "current": true on the new version, and remove that from any other past published version (but not from the current build entry)
  • mark "yes" in the Milestone column

Finishing the Publication Process

  • run the IGPublisher on {root}: org.hl7.fhir.publisher.jar -publish-update {root}
  • check the output: it should report that it changed N files for each published version of the IG (including previously published versions)
    • if problems, consult FHIR product director (and start again from the creating a local root directory)
  • if you are doing a milestone release: use FTP to delete the contents of ftp://hl7.org/fhir/{realm}/{code}: yes, delete all the files
  • use FTP to copy the entire contents of {root}/{realm}/{code} to ftp://hl7.org/fhir/{realm}/{code} - no need to upload files that have not changed
  • mark "yes" in the FTPed column
  • commit and push the changes to the FHIR IG registry to github & mark "yes" in the Register IG column
  • if this is a milestone publication, let Lloyd know that it's time to mark applied tasks as published, and considered for future use tasks as open
  • if this is a milestone publication (not for ballots) make an announcement on the https://chat.fhir.org/#narrow/stream/179240-Announcements/topic/FHIR.20Publication.20Announcement topic in Zulip using the following template:
 new Publication: [publication name] of the [IG Name] implementation guide: {canonical}/{subdir}

e.g. New Publication: STU Update 3.2 of the QI-Core implementation guide: http://hl7.org/fhir/us/qicore/STU32/