Publishing FHIR SDK Library Artifacts

Local Publishing

At the moment, we have the following FHIR SDK artifacts that need to be released so that they can be included as dependencies on reliant applications e.g. FHIR Core

• Android FHIR Common Library
• Android FHIR Engine Library
• Android FHIR Structured Data Capture Library
• Android FHIR Workflow Library
• Android FHIR Structured Data Capture - Barcode Extensions (contrib)
• Android FHIR Structured Data Capture - Location Widget Extensions (contrib)

Sometimes one wants to test the changes on the repo e.g. on the master branch without doing a remote release to Sonatype during development. It is possible to do this locally.

We can use the Android FHIR Structured Data Capture(SDC) Library as an example:

First, one needs to edit the Releases file buildSrc/src/main/kotlin/Releases.kt and add a unique(to your local machine) artifact identifier for the SDC library version. For instance, if on the master branch under the object DataCapture : LibraryArtifact the version reads 0.1.0-beta02, you might want to change that to 0.1.0-beta02-dev. Then later for new changes use 0.1.0-beta02-dev2 and so on.

This approach allows for multiple variations of local artifacts with your development changes and also helps avoid clashes with any remote artifact versions with a similar identifier.

Using the above example you then need to include the new version as a dependency in your build.gradle file and reference it like this:
api('org.smartregister.android.fhir:data-capture:0.1.0-beta02-dev') {

Once all the above is in place you just need to run the command:
./gradlew :datacapture:publishReleasePublicationToMavenLocal.

Your artifact should now be available under your maven local repo. location ~/.m2/repository/org/smartregister/android/fhir/data-capture/0.1.0-beta02-dev/

Building FHIR Core should now import the new artifact version. MavenLocal is already configured as an artifact source.

Note:

• This process needs to be repeated for all of the above aforementioned artifacts incase there are changes required there as well for testing.
• If you need to test changes present in other un-merged branches, you'd need to build the release artifact from a release branch that has all the other (un-merged) branch changes as well.
• For unmerged changes, always pay special attention to this file ResourceDatabase. The file contains migration scripts for the database. If the scripts end up in an illegal state, it would load to inconsistencies with the schema.

Remote Publishing

Credentials

In order to publish artifacts in OpenSRP's org.smartregister Sonatype group on maven, you need to be authenticated (and authorized). With the current configuration you need to set up your client credentials in the global gradle.properties file as show below

~/.gradle/gradle.properties

  sonatypeUsername=<username>
  sonatypePassword=<password>

Note: Name the property keys exactly as shown above. The credentials should not be pushed for version control else they will be available publicly. This set up will also work if you have your own Sonatype account you want to publish to.

Processes

1. On OpenSRP's Github fork of the Android FHIR SDK (Assuming there are new changes) click on Sync fork
2. Check out to master branch locally and pull the latest changes
3. Checkout to master-release branch and merge in master changes
4. Update the versions of the various modules you want to publish in the buildSrc/src/main/kotlin/Releases.kt file
5. Update the versions of the dependencies here used internally by the SDK
6. Make a commit with the updated versions and add a commit message in the format shown in the Commits section below
7. Push the commit to the master-release branch for tracking
8. Now that the master-release branch has all the latest updates from parent master, Check out to a new branch on your local with today's date in the dot separated double digit format DD-MM-YYYY and prefixe with release- e.g. release-20.10.2023
9. Merge in any other unmerged PR branches mentioned in the previous commit message and have not been merged to master yet. Ensure they branches have been updated with the latest master/main branch.
10. Publish the specific modules that you wanted. See the Publishing section below
11. After a successful publish to Maven push your release branch above for versioning.

Note: Always remember to check out the commits diff to tell which modules were affected by the latest changes. You can confirm that your module artifact was uploaded as it is available at https://oss.sonatype.org/content/repositories/snapshots/org/smartregister/

Commits

Each new commit message on the master-release branch should build upon the previous commit message. The format is as shown below, with the title listing all modules. Copy over the whole message and remove any entries for PRs already merged into master and add any new ones.

 SDK Release: Engine, SDC, Workflow, Contrib:Barcode, Common, Knowledger
 - With unmerged PR #1344
 - With unmerged PR #1542

See related sample commit here

Note: The above helps the next person doing a release to include exactly all the code updates that had been merged in previeously. If by the time we are publishing again the branch has already been merged into master branch then there'd be no need to add the message again. Also a glance at the header shows which specific modules were affected. Other than confirming the module changes that were incorporated after merging in master, check out which modules the unmerged PRs updated. The commit message is additive hence always use the previous commit message as a template for the new commit message (to either reduct or add the current required unmerged PRs).

Versioning

When versioning we extend from the current versions of the SDK library by adding -preview-SNAPSHOT suffix. Subsequently in future updates we increment that version e.g. -preview2-SNAPSHOT

In the buildSrc/src/main/kotlin/Releases.kt file, we edit the entry as shown below

buildSrc/src/main/kotlin/Releases.kt

object DataCapture : LibraryArtifact {
  override val artifactId = "data-capture"
  override val version = "1.0.0-preview-SNAPSHOT"
  override val name = "Android FHIR Structured Data Capture Library"
}

Publishing

Once all the above is in place you just need to run the command:

./gradlew :datacapture:publishReleasePublicationToSonatypeRepository --stacktrace

All the other modules follow a similar format, you only need to change the module you are targeting, e.g. to publish engine use the command:

./gradlew :engine:publishReleasePublicationToSonatypeRepository --stacktrace

Your artifact should now be available under the corresponding artifact group under your org. on Sonatype
e.g. see OpenSRP Standard Data Capture Artifacts