Skip to content

Release Process

Jump to bottom Edit New page
Kevin Dougan SmileCDR edited this page May 27, 2021 · 21 revisions

Creating a snapshot

This section outlines the process for pushing a new snapshot build of HAPI FHIR.

  • Build HAPI FHIR
mvn clean install
  • Assuming that passes, run a deploy. We skip the unit tests for this because the previous step passed and this avoids the possibility of intermittent failures causing mismatched versions.
mvn -Dmaven.test.skip clean deploy

Creating a Major or Minor Release

This section outlines the process for creating a new release of HAPI FHIR. This includes major releases (e.g. 5.0.0) and minor releases (e.g. 5.1.0) and is the process we follow once per quarter.

  • Make sure you have the latest version checked out
mvn pull
  • Create a release announcement and add it to /src/site/xdoc/index.xml
    • Note: There is no hard rule about what to include in the list of changes, since technically it's just duplication for what's in the changelog. Any major feature enhancements, breaking changes, interesting outside contributions, etc. are all good candidates. I always do a scan of the changlog and pick out the highlights.
    • Note: Make sure any links in these notes are absolute links. These notes get copied a few places, and relative links cause subtle problems.
  • Update the Maven project version in the pom.xml files (the command below updates all pom.xml files in the project)
# Put the real version number instead of 3.4.0 below!
mvn versions:set -DnewVersion=3.4.0
  • Check pom.xml to make sure that the version got correctly set
  • Build the release once more to make sure it builds
nice -n 20 mvn -P ALLMODULES,DIST -Dgpg.passphrase=PASS clean install
  • Update the date in src/changes/changes.xml under the new release number to be today's date in the format YYYY-MM-DD
  • Commit and push
git add .
git commit
git push
  • Push a build to the Maven repos
nice -n 20 mvn -P ALLMODULES,DIST -Dgpg.passphrase=PASS -Dmaven.test.skip clean deploy

  • Deploy the release to the OSS repo

    • Navigate to: https://oss.sonatype.org/#welcome
    • Log in
    • Click "Staging Repositories" on the left hand side
    • Select the HAPI release and click "close" (e.g. cauhn-####)
    • Wait a few minutes for the release to actually close. This takes up to 5 mins (you can do further steps below while you wait)
    • Click "refresh". If it shows as closed you are ready to move to the "release" step.
    • Click "release".
    • You can test whether the release is live by visiting https://repo1.maven.org/maven2/ca/uhn/hapi/fhir/hapi-fhir-base/ , but note that releases typically take up to 24 hours to propagate.

  • Create a new release by navigating to New Release

    • Give a tag similar to v3.4.0
    • Give a title similar to HAPI FHIR 3.4.0
    • Copy the release announcement from the index.html file, but make sure to remove any leading whitespace (the HTML will be treated as normal HTML if you trim the leading whitespace. Check the preview view to make sure you got it correctly.)
    • Attach binaries by selecting them from .../hapi-fhir/hapi-fhir-dist/target/. To ensure they are uploaded in the correct order, do them two at a time as follows:
      1. Standard Distribution archives
      2. CLI archives
      3. Android Distribution archives
      4. JPA Server Example archives
    • Save the release as a draft.

  • Deploy the site.

mvn -P SITE site-deploy

The command above may fail with the following output:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-scm-publish-plugin:1.1:publish-scm (scm-publish) on project hapi-fhir: Failed to delete removed files to SCM: Exception while executing SCM command. Error while executing command. Error while executing process. Cannot run program "/bin/sh" (in directory "/home/user/sites/scm/hapi-fhir"): error=7, Argument list too long -> [Help 1]
  • If the mvn -P SITE site-deploy command succeeded, the site is pushed and you can skip the next step. If it failed:
    • Navigate to .../sites/scm/hapi-fhir.
    • Commit and push
git add .
git commit
git push

  • Wait ~24 hours for the new release to appear in Maven Central. Once it's there, you can publish the release in GitHub.

  • Announcement to the Google Group.

  • Announcement to Zulip.

  • Update the Maven project version in the pom.xml files (the command below updates all pom.xml files in the project)

Update the Reference Projects

Update the HAPI FHIR version in the following projects:

Bump Git to the Next Version

# Put the real version number instead of 3.5.0 below!
mvn versions:set -DnewVersion=3.5.0-SNAPSHOT
  • Commit and push
git add .
git commit
git push

Hurrah!

Creating a Point Release

Point releases in HAPI FHIR (e.g. 5.2.1) are based on a Major or Minor release but with specific fixes backported.

Prepare Git Master

On git master, make sure your fix is committed. Ideally it should be merged with a squashed merge so that you can also cherry-pick it onto the point release branch.

You should also make the following changes, and commit them to master as well:

  • Add the new point version to VersionEnum
  • Add a backport tag to any relevant changelog YAML files that are being backported. For example, say you will be backporting a fix from 5.3.0 into 5.2.1, the changelog entry YAML file should be in the 5.3.0 changelog directory, but with an extra tag indicating that this fix was backported. This could look like:
---
type: fix
issue: 1234
title: A severe bug caused HAPI FHIR to set your house on fire if you look at it funny.
backport: 5.2.1

Make sure that these changes are committed in master - We will backport them to the point release branch too, but we want them to appear in the changelog for all time so they need to be in master as well.

Create the point release branch

The release branch will follow the naming scheme rel_x_x (e.g. rel_5_2). All point releases (i.e. tagged as v5.2.0, v5.2.1, v5.2.2, etc.) will be based off this branch, so it must be kept up to date with any fixes that go into this 5.2.x stream of point releases. Any future point releases in this stream will first start by creating a new branch off of rel_5_2.

Check if this branch exists. It may not exist if there hasn't been a point release for the current major/minor in which case you will need to create it. To create it:

  • Checkout the branch for the most recent/appropriate major/minor: git checkout rel_5_1
  • Create a new branch: git checkout -b rel_5_2

Backport your fixes

  • Copy your fixes to the release branch. Ideally using a git cherry-pick.
  • Make sure your fixes are committed to the release branch.

Publish

  • Build the release and publish to Maven Central
mvn -P DIST,ALLMODULES -Dgpg.passphrase=PASSWORD clean deploy
  • Log into https://oss.sonatype.org/ and publish the release
  • Log into the GitHub Releases Section and draft a new release. Make sure to pick the release branch instead of master and give it a tag like v5.2.3.
  • Upload the release files, which will appear in hapi-fhir-dist/target after running the Maven build command above.

Tag the version in GitHub

git tag v5.2.3

git push origin --tags

How to create a GPG Passphrase

Create the key

gpg --full-gen-key

Make sure to enter a passphrase. This passphrase is used in the above deploy commands.

Find your key ID

``

> gpg --list-secret-keys

sec   rsa3072 2021-01-20 [SC]
      ABC123ABC123ABC123ABC123
uid           [ultimate] Gary Graham <[email protected]>
ssb   rsa3072 2021-01-20 [E]

Upload your GPG public key

> gpg –keyserver hkp://keys.gnupg.net –send-key ABC123ABC123ABC123ABC123

gpg: sending key ABC123 to hkp://keys.gnupg.net
```

For more details on GPG, see [this link](https://blog.sonatype.com/2010/01/how-to-generate-pgp-signatures-with-maven/)
Add a custom footer
Add a custom sidebar
Clone this wiki locally