Release Guide

Container Images

The LinuxForHealth FHIR container images are published to the GitHub Packages Container Registry under LinuxForHealth.

Previously, the IBM FHIR Server container images were published at Docker Hub under ibmcom.

Maven Artifacts

The LinuxForHealth FHIR modules are published to Maven Central under groupId org.linuxforhealth.fhir.

Previously, the IBM FHIR Server modules were published under groupId com.ibm.fhir.

---

Checklist

New modules

• Check for any pull requests or issues with the label "new-module"
  • Think about whether there might be a new module that was not labeled (and encourage the author to use the label)
  • Should this module be deployed? if not, add a maven.deploy.skip property to the module.

Build

If you have added a new Implementation Guide (fhir-ig-*), ensure the following steps were performed:

• update fhir-validation/pom.xml with the latest implementation guide maven profile to support custom validation assembly builds
• update build/release/config/release.json with the custom profile under the fhir-parent entry
• update fhir-validation/src/main/assembly/README.txt to indicate the version of the new implementation guide
• update docs/src/pages/guides/FHIRValidationGuide.md to advertise our pre-packaged support for this new IG

When ready, check out the main branch and run the following:

git tag [major].[minor].[patch]
git push --tags

This tag-push kickoffs the following workflows in github actions:

• Build and Release
• Javadocs Build for Site

Monitor the actions for success (usually over an hour).

Sonatype OSSRH

• Navigate to https://oss.sonatype.org/#stagingRepositories
• Login as the fhirci user
• Ensure that all artifacts (jars, sources jars, test jars, poms, and zips) were uploaded to the staging repository with success
• Select the Staging repository and there should be 2 "repositories" listed
  • click Release on the first one (fhir-examples)
  • wait for that to propagate (20 minutes?)
  • login again and click Release on the second one (everything else)

DockerHub

• Ensure the latest images are now listed under https://github.com/orgs/LinuxForHealth/packages

Website

• Confirm the Javadocs are Posted
• Confirm the Site is updated with relevant details

Security

• Generate a PR with a minor change to an MD file, and label it ci-skip and security
• Let the Security Scan Run
• Once complete...
• Check the AppScan Report - https://cloud.appscan.com/AsoCUI/serviceui/main/myapps/oneapp/c4658cf4-e742-4410-99d4-d1c4084b856e/
• Check the Latest Dockle and Trivy Report

Release

• Review and summarize the Release description at https://github.com/LinuxForHealth/FHIR/releases

  • Especially check the version tag (e.g. YOUR_VERSION_HERE in the template below) on all the downloads in the "Using the release" section
  • Note any issues or PRs with the "deprecation" label for the Deprecated section
  • Note any issues or PRs with the "removal" label for the Removed section
  • Note any issues or PRs with the "configuration" label for the Migration Considerations
  • Note any issues or PRs with the "schema-change" label for the Migration Considerations
  • Note any issues or PRs with the "reindex" label for the Migration Considerations

• Download the artifacts from OSSRH / Maven Central and upload them to the GitHub Release

  • fhir-install-*.zip from both https://repo1.maven.org/maven2/org/linuxforhealth/fhir/fhir-install and the GitHub Build and Release workflow's Artifacts (Previously, fhir-server-distribution.zip)
  • fhir-persistence-schema-*-cli.jar from https://repo1.maven.org/maven2/org/linuxforhealth/fhir/fhir-persistence-schema
  • fhir-swagger-generator-*-cli.jar from https://repo1.maven.org/maven2/org/linuxforhealth/fhir/fhir-swagger-generator
  • fhir-bucket-*-cli.jar from https://repo1.maven.org/maven2/org/linuxforhealth/fhir/fhir-bucket
  • fhir-path-*-cli.jar from https://repo1.maven.org/maven2/org/linuxforhealth/fhir/fhir-path
  • fhir-validation-*.zip from https://repo1.maven.org/maven2/org/linuxforhealth/fhir/fhir-validation

Communication

• Announce on Zulip at https://chat.fhir.org/#narrow/stream/212434-LinuxForHealth/topic/releases

Draft the next release

• Increment the patch version in all the pom.xml files. We may chose to bump the major or minor version numbers later, but for now just do the patch. Eventually, we'd like to version each module independently and this step will go away.

PREVIOUS=4.3.1-SNAPSHOT
NEXT=4.3.2-SNAPSHOT
find . -iname pom.xml -not -path '**/target/*' -exec sed -i '' s/${PREVIOUS}/${NEXT}/g {} +

• Create a draft release for the next release, using the following template which is based on https://keepachangelog.com/en/1.0.0/, replacing YOUR_VERSION_HERE with the version tag you expect to use (e.g. bumping the patch number from the release you just made).

This version of the LinuxForHealth FHIR Server supports HL7 FHIR versions [4.0.1](https://www.hl7.org/fhir/r4/index.html) and [4.3.0](https://www.hl7.org/fhir/r4b/index.html).  

This release focuses on...

### Added
-

### Changed
- [IF NEEDED]The database schema version is now `SCHEMA_VERSION`
- [IF NEEDED(update the dates)][Dependency updates](https://github.com/LinuxForHealth/FHIR/issues?q=label:dependencies+is:closed+sort:updated-desc+is:merged+updated:2022-PREV_RELEASE_DATE..2022-CURR_RELEASE_DATE)

### Deprecated
-

### Removed
- 

### Fixed
- 

### Security
-

<a id="YOUR_VERSION_HERE-migration-considerations"/>

## Migration Considerations
To migrate from a prior version to version YOUR_VERSION_HERE:
1. Analyze configuration changes and prepare for the upgrade
   * SUMMARY OF FHIR-SERVER-CONFIG CHANGES FOR THE RELEASE
   * SUMMARY OF LIBERTY SERVER.XML CHANGES FOR THE RELEASE
2. Stop the server (or otherwise prevent write requests).
3. Perform a database back up.
4. Run the [fhir-persistence-schema-YOUR_VERSION_HERE-cli.jar --update-schema](https://github.com/LinuxForHealth/FHIR/blob/main/fhir-persistence-schema/docs/SchemaToolUsageGuide.md#deploy-new-schema-or-update-an-existing-schema) command.
5. Deploy the new server.
6. IF NEEDED Perform [re-indexing](https://linuxforhealth.github.io/FHIR/guides/FHIRSearchConfiguration#2-re-index).
   * SUMMARY OF REINDEX NEEDS FOR THE RELEASE

Special considerations for upgrading to YOUR_VERSION_HERE:
* fhir-persistence-schema: Prior to LinuxForHealth FHIR Server version 5.0.0, the default value for `--db-type` was `db2`. As of version 5.0.0, there is no longer a default value and `--db-type` must be specified every time.

If upgrading from a version prior to PRIOR_VERSION_HERE, be sure to review the applicable migration considerations:
* [PRIOR_VERSION_HERE migration considerations](https://github.com/LinuxForHealth/FHIR/releases#user-content-PRIOR_VERSION_HERE-migration-considerations)

Note: for schema migrations, only the latest version of the fhir-persistence-schema tool must be run.

## Using the Release
Run or extend the Docker image from https://github.com/LinuxForHealth/FHIR/pkgs/container/fhir-server or download [fhir-install-YOUR_VERSION_HERE.zip](https://github.com/LinuxForHealth/FHIR/releases/download/YOUR_VERSION_HERE/fhir-install-YOUR_VERSION_HERE.zip) and install as described at https://linuxforhealth.github.io/FHIR/guides/FHIRServerUsersGuide.

Executable jar files for the fhir-persistence-schema, fhir-swagger-generator, fhir-bucket, and fhir-path projects are also available:
* [fhir-persistence-schema-YOUR_VERSION_HERE-cli.jar](https://github.com/LinuxForHealth/FHIR/releases/download/YOUR_VERSION_HERE/fhir-persistence-schema-YOUR_VERSION_HERE-cli.jar)
* [fhir-swagger-generator-YOUR_VERSION_HERE-cli.jar](https://github.com/LinuxForHealth/FHIR/releases/download/YOUR_VERSION_HERE/fhir-swagger-generator-YOUR_VERSION_HERE-cli.jar)
* [fhir-bucket-YOUR_VERSION_HERE-cli.jar](https://github.com/LinuxForHealth/FHIR/releases/download/YOUR_VERSION_HERE/fhir-bucket-YOUR_VERSION_HERE-cli.jar)
* [fhir-path-YOUR_VERSION_HERE-cli.jar](https://github.com/LinuxForHealth/FHIR/releases/download/YOUR_VERSION_HERE/fhir-path-YOUR_VERSION_HERE-cli.jar)

Usage is documented in the corresponding README files:
* https://github.com/LinuxForHealth/FHIR/tree/main/fhir-persistence-schema
* https://github.com/LinuxForHealth/FHIR/tree/main/fhir-swagger-generator
* https://github.com/LinuxForHealth/FHIR/tree/main/fhir-bucket
* https://github.com/LinuxForHealth/FHIR/tree/main/fhir-path

For Maven users, all project binaries are posted to Maven Central with a groupId of `org.linuxforhealth.fhir` and a version of `YOUR_VERSION_HERE`.