On fhir.org there is a registry of published implementation guides for users to browse. One of the more popular exapmles of this would be the US Core Implmentation Guide.
These guides are maintained by the community, however, once changes are made and committed to the appropriate repositories, these updates then need to be released as versioned, web source files that can be displayed as part of the registry. This is done through a series of defined steps.
The website source for fhir.org is stored in the web-source repository. It’s
a Jekyll website, which is generated using the script contained in the committed run-jekyll.bat
file. Running this command will generate a folder called
output in the source folder.
package entry list
Within the packages repository there are a series of package
directories, containing the package data for the various published terminology and
support packages. Within in each of these directories, exists a file named
package-list.json, that contains the list
of all published versions for that given package. For example, the package list for the r4 test data package is located
Each of the entries in the list of released packages contains information like the
date, and others.
The most important thing to note with these entries is that, for packages, there can be only one entry marked as
"current": true. When creating a new release by adding a new entry in the list, the
"current": true field must be
removed from the previous release, and then added to the new entry.
The reason for this is that implementers can point to a specific version of a given implementation guide, such as
they can specify that they want the
current, or not specify a version at all (in which case
current is used).
Having to instances of
current will cause errors in the build process.
package releaser tool
In the IG Publisher repository, there is a tool that looks at the released packages according to the source. It then decides what changes it needs to make in the source to generate a new website. This is done by running the PackageReleaser tool.
This tool takes in two arguments, a source and a destination. The source is the local path on your computer, to the cloned packages directory in the packages project. The destination is the local path on your computer, to the cloned packages directory in the web-source project.
Publishing and Uploading a Release
At some point, someone will contact you to let you know that changes have been made to the packages, and a new release needs to be cut and published. When this happens, do the following:
- Clone the packages repository, and the web-source, and ensure they are up to date.
- Update the appropriate
package-list.jsonfile entry list with the new entry for that release.
- Run the PackageReleaser tool with the in source defined as the local packages directory within the packages repository, and the out destination pointing to the local packages directory in the web-source repository.
- In the web-source project, run the run-jekyll.bat script to generate the new Jekyll website.
This will generate the
outputfolder in the source directory.
- sftp the contents of the generated
outputfolder to the
fhir.org. You will need the proper credentials to do this. Currently, this is done by either Grahame or Mark, so please contact them to get this done.