Release Guide - LinuxForHealth/FHIR GitHub Wiki

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

Website

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

Security

Release

Communication

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