Skip to content

Project Versioning and Release Management

Jump to bottom
dotasek edited this page Jul 8, 2025 · 4 revisions

Versioning

Each version of HAPI-FHIR-JPAStarter-Project is based on the HAPI release version in its parent pom, combined with a revision number.

Format:

{HAPI-VERSION}-{REVISION-NUMBER}

Example:

8.0.0-1

The revision number starts at 1 whenever the HAPI version is updated. The revision number should be incremented whenever a new HAPI-FHIR-JPAStarter-Project release is needed using the same HAPI version. The revision number is set in the pom.xml file property hapi.fhir.jpa.server.starter.revision.

Thus a sequence of releases based starting with HAPI 8.0.0 would look as follows:

  • 8.0.0-1 (first release using HAPI 8.0.0)

  • 8.0.0-2 (bug fix in jpaserver-starter)

  • 8.0.0-3 (new config options provided in jpaserver-starter)

  • 8.2.0-1 (first release using HAPI 8.2.0)

  • ...

Note that there is no distinction between features or bug-fixes in the revision version.

The revision number is set in the pom.xml file property hapi.fhir.jpa.server.starter.revision.

Branch Management

master

A release of HAPI-FHIR-JPAStarter-Project is defined as a tagged commit in the master branch with a corresponding push of the project Docker images to DockerHub. The history of the master branch may contain multiple commits with the same version; only a tagged commit constitutes a valid release.

release tracking branch

A release tracking branch should always use a SNAPSHOT version of HAPI-FHIR, and a revision number of 1.

HAPI Version Tracking

The HAPI-FHIR JPA-Starter project uses the HAPI-FHIR project as a parent dependency. However, it is not tested as part of the HAPI-FHIR project, and as such, changes to HAPI-FHIR can break HAPI-FHIR JPA-Starter.

In order to mitigate this, at the start of every HAPI-FHIR release cycle, the HAPI-FHIR JPA-Starter project should create a branch that uses the current HAPI-FHIR SNAPSHOT version.

For example, in a release cycle for release 7.6.0, HAPI-FHIR will set its version to 7.5.0-SNAPSHOT. Within the HAPI-FHIR-JPA-Starter project, the following should be done:

  • A branch (rel_7_5_tracking, for example) should be created
  • The parent version in that branch's pom should be set to 7.5.0-SNAPSHOT.
  • The hapi.fhir.jpa.server.starter.revision property should always be set to 1 in release tracking branches (see Branch Management)
  • A Draft PR of that branch should be created. This will allow automated checks to be run.
  • On a weekly basis, the following maintenance should be done on the Draft PR:
    • Any commits to the master branch should be tested and then merged into the Draft PR.
    • The automated checks should be re-run to verify that any changes to HAPI-FHIR haven't broken any functionality.

Once a release is made for HAPI-FHIR (7.6.0, in our example), the following should be one within the HAPI-FHIR-JPA-Starter project:

  • The parent version in the tracking branch's pom should be set to the release version (7.6.0 in our example)
  • The Draft PR attached to the branch should be made ready for review.
  • All automated checks should be verified to pass.
  • The PR should be merged into the master branch.
  • A release should be made from the master branch.

Release process

Increase the revision number if needed (see the Versioning). The revision number is set in the pom.xml file property hapi.fhir.jpa.server.starter.revision.

Each release consists of two steps; running the release pipeline, and creating a GitHub release.

Running the release pipeline.

  1. Ensure you have adequate permission to push tags to the master branch on https://github.com/hapifhir/hapi-fhir-jpaserver-starter
  2. Clone the git repository
  3. Ensure you are on the master branch.
  4. Tag with the appropriate version: git tag -a -m "Release 7.0.0-1" image/v7.0.0-1. IMPORTANT: use the format image/vW.X.Y-Z for this tag. The release pipeline uses this format to appropriately tag docker pushes. Without this format, the step will fail.
  5. Push the tag via git: git push --follow-tags origin master

After these steps, GitHub Actions should begin the release pipeline, which should be observable here. When complete, this should produce two images, vW.X.Y-Z (or latest) and vW.X.Y-Z-tomcat (or latest-tomcat), visible here.

Creating a GitHub release.

  1. Go to the releases section of the GitHub repository (https://github.com/hapifhir/hapi-fhir-jpaserver-starter/releases).
  2. Click on Draft a new release
  3. Use the Choose a tag dropdown menu to select the tag you created earlier.
  4. Click on Generate release notes to auto-fill the release notes and title.
  5. Click on Publish release to complete the process.

After these steps, your release should be visible in the releases section of the GitHub repository.

Clone this wiki locally