-
Notifications
You must be signed in to change notification settings - Fork 1
IG build for Publication
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"
- delete fhir build caches in your {user}/.fhir folder.
- might need to clean out the %TEMP% and %TMP%
- 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
-
- 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
- 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:
, nothttp:
- 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)
- must be
- 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-use
- Continuous Integration build is
ci-build
- final-text (normative) will be
release
- public-comment will need to be
- 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.
- so
- 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., NOTcurrent
)template = ihe.fhir.template
- build your target IG as normal (past procedures would have also used the
-publish
, this is not needed now)
_genonce
- prepare your
publication-request.json
-- (formerly package-list.json, which has been retired)
- keep this file revision controlled in root of the project github
- documentation on publication-request.json
-
if you have a publish.ini in the project, delete it. This is no longer used with -go-publish
-
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)
- 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.
- 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.
- 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}.
-
If this is a new IG, then you need to edit the
publications/publish-setup.json
and add to thelayout-rules
the details for this new IG. -
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 **
-
add your version specific sub-folder to the
robots.txt
at the root ofprofiles.ihe.net
. This prevents searches (e.g., google) from recommending anything other than formal publication folder. --> https://github.com/IHE/publications -
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.
-
update appropriate domain
index.html
to reference properly the new release, or version folder for public-comments -
Commit all updates back to
publications
repo as necessary. -
When no further changes happen, then Mary will
filezilla
the content over toprofiles.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
- 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
-
commit IG project changes to the IG project github repo. Usually just the version and release tagging updates.
-
tag the IG project repo with this version details -- https://github.com/IHE/publications/wiki/Revision-Management
-
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 beci-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
-
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. -
redirect links to the former PDF to the new IG folder
-
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.
- 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