Publishing Packages

Background

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.

Moving Parts

website source

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

Each of the entries in the list of released packages contains information like the version, desc, 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 0.2.1, 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:

  1. Clone the packages repository, and the web-source, and ensure they are up to date.
  2. Update the appropriate package-list.json file entry list with the new entry for that release.
  3. 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.
  4. In the web-source project, run the run-jekyll.bat script to generate the new Jekyll website. This will generate the output folder in the source directory.
  5. sftp the contents of the generated output folder to the /var/www/html/ directory on 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.

Updated: