Merge pull request #154 from dhis2/api-doc-and-release

[skip publish]: Api docs and github release workflows

.github/workflows/dokka.yml

@@ -0,0 +1,17 @@
+name: Deploy API docs
+
+on:
+  push:
+    branches:
+      - main
+      - master
+
+  workflow_dispatch:
+
+jobs:
+  api-docs:
+    uses: dhis2/workflows/.github/workflows/publish-dokka-to-github-pages.yml@a0b4d50d9606c734b785451774a325846931f1ee
+    with:
+      java_version: 21
+      gradle_args: "-PremoveSnapshotSuffix"
+      output_folder: "api"

.github/workflows/main.yml

@@ -10,7 +10,7 @@ on:
 
 jobs:
   unit-test:
-    name: Run tests
+    name: Run checks
     if: ${{ github.event.pull_request.merged == true }}
     runs-on: ubuntu-latest
     steps:
@@ -27,6 +27,9 @@ jobs:
       - name: Test
         run: ./gradlew clean allTests
 
+      - name: API Check
+        run: ./gradlew apiCheck
+
   publish:
     needs: unit-test
     if: ${{ github.event.pull_request.merged == true && !contains(github.event.pull_request.title, '[skip publish]') }}
@@ -60,3 +63,10 @@ jobs:
         run: ./.github/workflows/scripts/publish-npm-prod.sh
         env:
           NPMJS_TOKEN: ${{ secrets.DHIS2_BOT_NPM_TOKEN }}
+
+  github-release:
+    uses: dhis2/workflows/.github/workflows/gradle-publish-release-to-github.yml@10b6e0d0662a579b6057a1f7a51a94d41d53a913
+    needs: publish
+    with:
+      java_version: 21
+      gradle_args: "-PremoveSnapshotSuffix"

.github/workflows/pull_request.yml

@@ -5,7 +5,7 @@ on:
 
 jobs:
   unit-test:
-    name: Run tests
+    name: Run Checks
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -21,6 +21,9 @@ jobs:
       - name: Test
         run: ./gradlew clean allTests
 
+      - name: API Check
+        run: ./gradlew apiCheck
+
   publish:
     name: Publish
     needs: unit-test

README.md

@@ -1,3 +1,7 @@
+[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.hisp.dhis.rules/rule-engine/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.hisp.dhis.rules/rule-engine)
+[![NPM Version](https://img.shields.io/npm/v/@dhis2/rule-engine)](https://www.npmjs.com/package/@dhis2/rule-engine)
+[![KDoc link](https://img.shields.io/badge/API_reference-KDoc-blue)](https://dhis2.github.io/dhis2-rule-engine/api/)
+
 ### RuleEngine (WIP)
 
 #### Initialization
@@ -64,6 +68,13 @@ List of supported environment (contextual) variables:
 
 ## Development
 
+### API Validator
+This library uses the [Binary Compatibility Validator plugin](https://github.com/Kotlin/binary-compatibility-validator), which verifies that there are no changes in the public API of the library.
+
+The way of work is: there is a file generated by the plugin (`api/expression-parser.api`) with the binary representation of the expected public API. The plugin has a task (`apiCheck`) that verifies that the public API of the code matches the expected API in the file.
+
+If there is an intentional change in the public API, this file must be updated to reflect the changes and included as part of the pull request. It can be updated running the task `apiDump`. This task can be run in the command line (`./gradlew apiDump`) or using Gradle window in Intellij.
+
 ### Version
 Library version is defined in the file `build.gradle.kts`. The version must be manually increased
 and include the `-SNAPSHOT` suffix. Please make sure the version is updated before opening the PR.

build.gradle.kts

@@ -2,6 +2,7 @@ plugins {
     kotlin("multiplatform")
     id("maven-publish-conventions")
     id("npm-publish-conventions")
+    alias(libs.plugins.api.compatibility)
 }
 
 repositories {

gradle/libs.versions.toml

@@ -1,8 +1,9 @@
 [versions]
 kotlin = "2.0.21"
-dokka = "1.9.10"
+dokka = "2.0.0"
 nexusPublish = "2.0.0"
 npmPublish = "3.5.2"
+apiCompatibility ="0.17.0"
 kotlinxDatetime = "0.6.1"
 kotlinJsWrappers = "1.0.0-pre.830"
 slf4jApi = "1.7.36"
@@ -21,5 +22,6 @@ slf4j-api = { group = "org.slf4j", name = "slf4j-api", version.ref= "slf4jApi"}
 dhis-expression-parser = { group = "org.hisp.dhis.lib.expression", name = "expression-parser", version.ref = "expressionParser"}
 
 [plugins]
+api-compatibility = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version.ref = "apiCompatibility" }
 
 [bundles]