IG build for Publication

This process that works today, might not work tomorrow. History proves this breaks often. **Now using -go-publish **

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

• HL7 Process+for+Publishing+a+FHIR+IG
• HL7 Maintaining a FHIR IG Publication

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.

2. 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

3. 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

4. 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 will need to be ballot
  • after publication the releaseLabel should be set back to 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.
  • note that IG publisher 1.1.111 had a bug with semver.
  • after publication the version should be incremented at the patch level and postfixed with -current

5. build your target IG as normal (past procedures would have also used the -publish, this is not needed now)

  _genonce 

6. prepare your package-list.json and put into the website directory

• keep this file revision controlled in root of the project github
• it needs to properly identify the project
• documentation on package-list.json https://confluence.hl7.org/display/FHIR/FHIR+IG+PackageList+doco
• this file needs to have a new entry describing the new publication version
• the last entry should have the current removed from it
• if publishing a non-milestone it is okay for multiple to be identified as current
• if this is a conversion of a formerly published PDF, then that last PDF version can be mentioned as the oldest history entry. The path should be to the version specific PDF (that with the date and version in the name of the PDF)
• the category element should use one of the categories found in the IG registry, but can use something new.
• sequence - is the IHE lifecycle milestone, ususally Public Comment or Trial Implementation
• status - must use a defined code - ballot, trial-use, ci-build. or others (see https://confluence.hl7.org/display/FHIR/FHIR+IG+PackageList+doco)
• package-id - must be the proper package-id
• canonical - must be the proper canonical
• title - is the title to be shown in the IG registry - Indicate IHE - e.g. "IHE Mobile Access to Health Documents"
• introduction - is the (markdown) introduction to be shown in the IG registry - usually pulled from the front page of the IG

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

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

  git clone https://github.com/IHE/fhir-ig-history-template.git

• if you already have a clone, make sure it is up-to-date (git pull)

9. 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.

10. 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

11. 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}.

13. Do publisher magic

• TWO use-cases
  • milestone -- when you want this new release to go into the profiles.ihe.net project and version folders
    • usually used for formal releases
  • not milestone -- when you want the new versino to go only into the version folder
    • usually for public-comments or temporary release for an event like connectathon
  • thus usually using -milestone parameter shown below. but if not doing a milestone, then omit the -milestone parameter
• 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 -jar input-cache\publisher.jar -go-publish -source . -destination C:\Users\john.moehrke\Git\publications -registry C:\Users\john.moehrke\Git\ig-registry\fhir-ig-list.json -history C:\Users\john.moehrke\Git\ihe-ig-history-template -milestone

• 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 destinatino 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 **

14. 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

15. 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.

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

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

18. 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

19. tag the publications repo including high level why the release.

• Best Practice is to use the mailchimp notice of the release as the text of the tag, and include the URL to the mailchimp as it is a persistant URL.
• https://github.com/IHE/publications/wiki/Revision-Management

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

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

22. update the IG project to the next minor version 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

23. 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.

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

history

March 2022 -- moved to using go-publish. Which automates much, but does require things be setup perfectly.

This was transcribed from discussion on zulip chat

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