@clue/clue-shared v19.0.12

clue-shared

Code shared between the Clue platforms (Android, iOS, and Backend) that includes the cycle prediction algorithm, cycle analysis processor, symptom forecaster, and more. This project is migrated from and supersedes the clue-algorithm project.

Changelog

See CHANGELOG.md.

Requirements

Make sure you have JDK 1.8 or newer installed to build the JVM and JS targets, and XCode installed to build the iOS target.

java -version
xcodebuild -version

Useful commands

# Run all the tests
./gradlew test

# Clean the local repository from build artifacts
./gradlew clean

# Create the build artifacts only
./gradlew assemble

# Clean the build artifacts, run all the checks, and create the build artifacts
./gradlew clean build

Project walk-through

This project uses Kotlin Multiplatform 1.4+ and leverages its hierarchical structure to target the jvm, js, and ios platforms.

Common code (src/commonMain)

This is where the core business logic is located.

When building the artifacts for each platform target, in addition to the platform-specific sources below, the Kotlin code in this directory will be used to build the platform artifact. This means that any code added or changed here will be available from every platform and only platform-specific code (such as variants of commonMain APIs) is needed in the platform-specific sources below.

JVM

The JVM target is mostly composed of the common sources.

The JVM Maven artifact is used by the Android App and the Kotlin services in the Backend.

Javascript/Typescript

The JS target also includes code from src/jsMain which contains specific APIs that wrap code called from the commonMain sources. The Kotlin/JS compiler automatically interops with both sources to generate the JS build file. Additionally, the Typescript type definition file (clue-shared.d.ts) is generated using a custom Gradle task that reads specific inline comments from all files from both sources (see GenerateTypescriptTypeDefinitionTask).

The JS/TS artifact is used by the Typescript services in the Backend (see clue-services).

iOS

The iOS target is composed of the common sources and any iOS-specific APIs which are located in src/iosMain.

This iOS artifact is a Swift package that is created using the task ./gradlew createSwiftPackage and published to a separate Github repo with release tags.

Artifacts

Below is a table of the artifact repositories used for each target.

How to publish a new version?

Semver

First, find out if this release should be a patch, minor or major version. Please refer to Semantic Versioning to understand the subtleties of each level. The change log can help you in this task.

Version preparation

Update the projectVersion in version.gradle

Adding version in CHANGELOG.md

Add a header with the new version number and the current date right below the Unreleased header in CHANGELOG.md.

Releasing the new version

The new version releases will automatically be published from Jenkins whenever a PR with changes to version.properties is being merged into the branch main. This uses the Gradle tasks backendPublish, androidPublish, and iosPublish.

Prerequisites

In order to publish modules to the Maven repository, to the NPM registry, and a notification to Slack, the following environment variables are required:

• CLUE_MAVEN_REPO_ACCESS_KEY — Access key of the "jenkins-maven-repo" user in our AWS account
• CLUE_MAVEN_REPO_ACCESS_KEY —  Secret key of the "jenkins-maven-repo" user in our AWS account
• ARTIFACTORY_PASSWORD — Password for this user
• NPM_AUTH_TOKEN — Auth token for writing to the "biowink" organization in npmjs.org
• SLACK_USERNAME — The username to post into Slack as, e.g. "Jenkins"
• SLACK_WEBHOOK_URL — The webhook URL of the Slack integration

Write-access to the "biowink/shared-code-ios-releases" Git repository is also necessary to publish release tags.

How to add a feature?

Implement the business logic

How?

• Use a traditional Kotlin style.

Where?

• Sources: src/commonMain
• Tests: src/jvmTest

Implement a Typescript API

How?

• Use JS-friendly subset of Kotlin types (Array over List, dynamic over class instances)
• Skip packages: expose everything at the root level
• Within Kotlin sources, use lines starting with // d.ts: to describe the Typescript API

Where?

• Sources: src/jsMain, src/commonMain
• Tests: src/jsTest

Implement an Objective C API

Where?

• Sources: src/iosMain
• Tests: src/iosTest

Update the CHANGELOG

Submit a PR

Upgrading the Gradle version

Find out the latest release number of Gradle here: https://gradle.org/releases/

Run the following command twice:

./gradlew wrapper --distribution-type=all --gradle-version=<release number>

Submit the changes in a dedicated commit.