Skip to content

IG build for Publication

Jump to bottom
John Moehrke edited this page Oct 13, 2023 · 46 revisions

This process that works today, might not work tomorrow. History proves this breaks often.

The formal process that HL7 uses will evolve, and that evolution will likely break things

Here is pseudo-code (shell code) for what seems to work

Given you have a target IG named "test-ig", in the XXX IHE domain, and it is at version "0.1.0"

  1. delete fhir build caches in your {user}/.fhir folder.
  • might need to clean out the %TEMP% and %TMP%
  1. make local clone of the target github repo (e.g. test-ig)
  • if you already have a clone, make sure it is up-to-date (git pull)
  • if you previously had built it locally, delete all folders created by builds
    • input-cache, output, temp, template, fsh-generated, etc
  1. update the publisher tooling in your target IG clone. Both Sushi and Publisher need to be up-to-date. Update sushi using npm install as shown below. Update the publisher using _updatePublisher and answering "y" (second question you should also answer "y")
  $ npm install -g fsh-sushi
  $ _updatePublisher
  1. Set project specific release fields
  • i.e., sushi-config.yaml, or the IG .xml if not using sushi
  • the id must be of the format ihe.{domain}.{project}
    • where this is all lowercase
    • where domain is the acronym for your domain
    • where project usually is the acronym for your project
  • the canonical must be of the format https://profiles.ihe.net/{Domain}/{Project}
    • must be https:, not http:
    • where the canonical can be mixed case, but must be the same case everywhere
    • where Domain is often the uppercase acronym for the domain (e.g. ITI, PCC, RAD)
    • where Project is often the uppercase acronym for the project (e.g. ATNA, mCSD, PDQm, MHD)
  • the name is usually the id with '_' replacing the '.', and using mixed case.
  • the releaseLabel
    • public-comment will need to be ballot
    • trial-implementation will be Trial-Implementation
    • Continuous Integration build is ci-build
  • the date should be the date you intend to be formal publication date (leave date unspecified and it will be the date you build the publication)
    • after publication the date should be set back to not specified
  • the version may be in semver format
    • note that any version with a '-' in it will not be recognized as a formal release.
    • the postfix is typically used to indicate releases leading up to the version specified
      • so 1.1.1-comment is read as the public-comment release that will eventually become 1.1.1.
    • after publication the version should be incremented at the patch level and postfixed with -current
  • any dependency on other IGs should be version specific
  • the ig.ini should be using a the released version of the IHE template (i.e., NOT current)
    • template = ihe.fhir.template
  1. build your target IG as normal (past procedures would have also used the -publish, this is not needed now)
  _genonce
  1. prepare your publication-request.json -- (formerly package-list.json, which has been retired)

  1. if you have a publish.ini in the project, delete it. This is no longer used with -go-publish

  2. make local clones of the HL7 fhir-ig-history-template https://github.com/HL7/fhir-ig-history-template

  git clone https://github.com/HL7/fhir-ig-history-template.git
  • if you already have a clone, make sure it is up-to-date (git pull)
  1. make fork of ig-registry and clone that fork locally
  $ git clone https://github.com/FHIR/ig-registry.git
  • if you already have a fork, make sure it is up-to-date in addition to your local clone of that fork.
  1. make a local clone of the IHE publications repository https://github.com/IHE/publications
  • this is the staging and revision control for the https://profiles.ihe.net
  • if you previously had a clone, make sure it is fully updated
  • you might need to create an empty ig-build-zips folder if one does not exist.
  1. Create a local branch on the publications local clone repository
  • this helps with managing failures during the build, as you will need to revert to previous if anything goes wrong in the next step.
  • in TortoisGit - Right click --> TortoisGit --> Create Branch...
  • the name of the branch is not too important. I tend to use my lastname-{project}.

  1. If this is a new IG, then you need to edit the publications/publish-setup.json and add to the layout-rules the details for this new IG.

  2. Do publisher magic

  • execute this from the project folder -- i.e. why -source .
  • the paths you give to the publisher need to be full paths. It does not support relative paths (e.g. can't say '..\ig-registry') This is a bug that might eventually be fixed.
  • example below shows using full paths to the four repos mentioned above. adjust as you might need.
java -Dfile.encoding-UTF-8 -jar input-cache\publisher.jar -go-publish -source {path to source IG project} -web C:\Users\johnm\git\publications -temp C:\Users\johnm\temp -registry C:\Users\johnm\git\ig-registry\fhir-ig-list.json -history C:\Users\johnm\git\fhir-ig-history-template -templates C:\Users\johnm\git\publications\templates
  • make sure it succeeded.
  • make sure it updated the destination project folder as expected (root and version folders)
  • make sure it updated the destination fhir\package-feed.xml
  • make sure it updated the destination fhir\publication-feed.xml

** If any error happened... you will need to revert completely the publications repo, and delete the version folder where new files were added **

  1. add your version specific sub-folder to the robots.txt at the root of profiles.ihe.net. This prevents searches (e.g., google) from recommending anything other than formal publication folder. --> https://github.com/IHE/publications

  2. follow the publications process for quality checks and publication. (Any quality check failures, likely require changes to the IG build)

  • This must be done in concert with Mary.

  1. update appropriate domain index.html to reference properly the new release, or version folder for public-comments

  2. Commit all updates back to publications repo as necessary.

  3. When no further changes happen, then Mary will filezilla the content over to profiles.ihe.net web site

  • Make sure to copy the robots.txt, fhir/package-feed.xml, fhir/publications-feed/xml, domain index, and the whole project folder.
  • other changes should also be moved over as the publications repo will be tagged
  1. tag the publications repo including high level why the release.

  1. commit IG project changes to the IG project github repo. Usually just the version and release tagging updates.

  2. tag the IG project repo with this version details -- https://github.com/IHE/publications/wiki/Revision-Management

  3. update the IG project to the next patch version (third digit) and back to ci-build, and commit that to github. This prepares the ci-build as different than the release.

  • i.e., sushi-config.yaml, or the IG .xml if not using sushi
  • the releaseLabel will need to be ci-build
  • comment out the date (leave date unspecified and it will be the date you build the publication)
  • the version go to the next patch number, and add -current
  • any dependency should change to current

  1. commit the changes to ig-registry to your fork and create pull-request to HL7 authorities. Note look for the IGs you are adding, there might be old and now improper entries for original PDF versions.

  2. redirect links to the former PDF to the new IG folder

  3. make sure there is a Profiles page on the http://wiki.ihe.net. This wiki listing is referenced in the ISO standard for the IHE process.

history

  • March 2022 -- moved to using go-publish. Which automates much, but does require things be setup perfectly.
  • October 2022 -- changed to direct use of HL7 history template, with IHE customizations in publications repo

This was transcribed from discussion on zulip chat

Alternate script https://confluence.hl7.org/pages/viewpage.action?pageId=104580055

Clone this wiki locally