Building the SHR Project

A series of walkthrough for building and deploying new versions of the SHR to the StandardHealthRecord.org.

Github Repositories involved

There are several different github repositories that you'll need to have cloned and set up on your machine:

• SHR_Spec: The project containing the most recent version of the SHR spec.
• SHR_Command-Line Interface: The command line tools used to generate the FHIR Implementation Guide (IG) and the SHR JSON file needed for the SSVE.
• SHR Specification Viewer and Editor (SSVE): The JavaScript tool used to process the SHR Specification and build HTML files corresponding to the SHR data elements, code systems, value sets and visualizations.
• Standard Health Record Homepage: The directory used to host standardhealthrecord.org.
• Your own fork of Standard Health Record Homepage: If you're not sure how to get started on this take a look at this subsection of the shr repository that walks through how to fork and build the project.

Take a look at each project's README and make sure that you have all the necessary technologies downloaded and set up.

General Overview

There are four major subtasks involved in building and deploying a new version of the shr.org page.

1. Update the FHIR IG if needed;
2. Update the SHR Specification if needed;
3. Deploy the website to sandbox for testing; and
4. Deploy the website to production.

Below you will find a detailed walk through for each of these steps.

Update the FHIR IG

The FHIR IG needs to be updated anytime changes are made to the SHR specification. Below you will see the steps required to build a new version of the IG, modify it as necessary, and move it into the appropriate SHR project folder.

1. Ensure that you have both the SHR_Spec and the SHR_Command-Line Interface cloned on your local machine.
2. Enter the SHR CLI directory
3. Set up your local enviornment for the SHR CLI. To do this, see the setup section of the SHR CLI Readme
4. Exporting SHR to Markdown, HTML, JSON, and FHIR. To do this, see the export section of the SHR CLI Readme
5. Ensure Java Runtime Environment (JRE) or Java SDK (JSDK) are installed on your machine
6. Ensure that Jekyll (Mac/Linux or Windows) is installed on your machine
7. Generate the IG, instructions for which can be found in this section of the SHR CLI Readme. If your system requires a proxy to access the internet, you'll need to take a more complex approach than above as described here
8. Append YAML front-matter providing redirect links to pages whose SHR IG canonical links differ from those of the SHR.org links. From within the ./out/fhir directory, run python3 shr-format-FHIR-files.py.
9. Copy and paste the FHIR IG content (the contents of ./out/fhir/guide/output) into your fork of the shr.org project, into the fhir folder. That is, into /some/path/to/your-fork-of-shr/fhir

After this, your fork of SHR.org should contain updated FHIR IG files.

Update the SHR Specification

SHR.org needs updated versions of the SHR Specification HTML files anytime changes are made to the SHR specification. Below you will see the steps required to build a new version of the SHR Spec HTML files and to move it into the appropriate SHR project folder.

1. Ensure that you have the SHR_Spec, the SHR_Command-Line Interface, and the SHR Specification Viewer and Editor (SSVE) cloned and set up on your local machine.
2. Enter the SHR CLI directory
3. Set up your local enviornment for the SHR CLI. To do this, see the setup section of the SHR CLI Readme
4. Exporting SHR to Markdown, HTML, JSON, and FHIR. To do this, see the export section of the SHR CLI Readme
5. Rename the output SHR JSON file, found in some/path/to/shr_cli/out/json, from definitions.json to data.json.
6. Copy data.json from some/path/to/shr_cli/out/json to /some/path/to/spec_json2html/assets/data/. If this asks to rewrite a file, allow it. Should you need to revert to the old json file, you can always use git to checkout an older commit
7. From the central SSVE directoty, /some/path/to/spec_json2html/, use the grunt command -- grunt -- to generate a new copy of the HTML files, output located in some/path/to/spec_json2html/dist/shr.
8. Copy over all the output shr files into the SHR Sandbox, from some/path/to/spec_json2html/dist/shr to some/path/to/your-fork-of-shr/shr. If this asks to rewrite files, you should allow it.
9. From the SHR fork central directory, build the project using bundle exec jekyll serve. You should then be able to view the project by visiting localhost:4000 in your browser.

TODO: Automatically update date modified.

Update the SHR Reference Models

SHR.org needs an updated version of the shr reference models anytime changes are made to the SHR specification. Below you will see the steps required to build a new version of the SHR Reference Model.

1. Ensure that you have both the SHR_Spec and the SHR_Command-Line Interface cloned on your local machine.
2. Enter the SHR CLI directory
3. Set up your local enviornment for the SHR CLI. To do this, see the setup section of the SHR CLI Readme
4. Exporting SHR to Markdown, HTML, JSON, and FHIR. To do this, see the export section of the SHR CLI Readme
5. Copy the contents of the Modeldoc output (./out/modeldoc) to the reference-model of your fork, that is to some/path/to/your-fork-of-shr/reference-model, replacing all previous files in the folder.

You can view the reference models in your browser by opening reference-model/index.html

Deploy to Sandbox

Below you will find the steps involved in deploying all of your changes to your sandbox fork. This will be how you test changes before deploying anything out to production.

1. Push all of your changes to your GitHub repository fork.
2. On the GitHub page for your fork, go to the settings tab and find the section for repository name.
3. Change repository name from standardhealth.github.io to your-account-name.github.io (yes, that means put your github account name there). If you are already using this page for something else, consider backing up and storing that other branch somewhere else or using GitHub pages to host your content. If this reads as gibberish to you, stick to the script as much as possible.
4. Make sure that the changes you want to view are on the master branch.
5. Open up the page your-account-name.github.io.

Deploy to Production

Below you will find the steps involved in deploying all of your changes in your sandbox fork to production. In short, after testing your changes a) make sure you have the CNAME file back; and b) make a pull request. A more detailed procesure is below.

1. Run browser tests mentioned in the SHR.org readme on localhost by building the project with bundle exec jekyll serve.
2. Push changes to your GitHub fork of the repository.
3. Run tests on mobile devices when your-account-name.github.io has been updated.
4. Replace the CNAME file you deleted when you first pulled the repository; the file should be named CNAME and have in it standardhealthrecord.org.
5. If everything checks out, issue a pull request with the main repository.
6. Wait for someone in the collaborative to review your changes, merge to master, and see your contributions go live!
7. After your pull request has been merged, remove the CNAME file from your local repo again. Make sure to put this off until the changes have merged; pull requests continue to monitor changes you make even after you make the request.