Convert Gradle to Maven Build (#261)

* Issue #217 - Convert and port Gradle to Maven build for web5-kt

* No security or license issues
* All modules build and tests pass
* Dependencies all correctly set via dependencyManagement which may be consumed by other projects (ie. tbDEX)
* Ported Dokka to use Dokka CLI in GitHub Actions and instructions to run locally
* Change: API Docs via Dokka now have no left sidebar because Gradle plugin enabled multimodule for us.
* Detekt ported through Maven plugin
* Ported Kover; we have coverage via CodeCov
* Switched to use TBD Artifactory for single repo declaration to get 3rdparty deps not in Maven Central
* Update README to reflect new build usage
* Publish to TBD Artifactory
* While we are at it, renames to GitHub Actions for clarity and correctness
* Set Surefire patterns to run Test Vectors
* Publish every build as a SNAPSHOT in format X.Y.Z-commit-$shortSHA-SNAPSHOT
* Validate that SNAPSHOT publishing has a version defined that ends in -SNAPSHOT
* SNAPSHOTs deployed to TBD Artifactory for every push to main, with version commit-$shortSHA-SNAPSHOT
* TBD Artifactory Release and Publish, with tagging of git
* API Docs Publishing - Verifiable at: https://alrubinger.github.io/web5-kt/docs/htmlMultiModule/index.html
* Maven Central Publishing
* Include sources in publishing
* Sign all artifacts (POMs, JARs, Source JARs) with GPG in deploy to Artifactory and Maven Central
* Only require one input (the release version) to trigger a release. Infer the next development version as a patch increment above the release version
* Introduce a distribution POM to bring in all Web5 deps in a single declaration
* Keep pom.xml effectively versionless at 0.0.0-main-SNAPSHOT; version at release time
* Publish to Maven Central on successful release and publish to TBD
  Artifactory
* Update README to reflect changes above and document all build and
  pipeline features
* Do not double-trigger uploads to Artifactory, Test Vectors, or CodeCov by separating out MacOS and Ubuntu jobs
* Make 'distribution' folder for the distribution pom.xml so that tbdex-kt can follow same convention
* Add jose to Dokka API Docs generation
* Rebased all work atop c1c8f3e, tag: v0.17.0
* Address Jiyoon PR Review: add names for all workflow jobs, document SNAPSHOT version format, add TBD OSS SNAPSHOT and Release repos to POM

TODO:
* Switch ALRubinger in SCM configuration of pom.xml to TBD again
* Remove the comments at the end of build-test-publish workflow to
  re-enable sdk-report-runner

* Issue #217: Remove testing configs to be ready for merge

* Removes unnecessary comment

* adding more git command examples for pushing to web5-spec module

---------

Co-authored-by: Leo Ribeiro <[email protected]>
Co-authored-by: Jiyoon Koo <[email protected]>

.github/workflows/ci.yml

@@ -1,20 +1,36 @@
+# Runs on every commit to main. This is the main CI job; it runs in MacOS and Ubuntu environments which:
+# * Build
+# * Run tests
+#
+# In the Ubuntu environment only, to avoid double uploads from MacOS, it also:
+# * Uploads Test reports to BuildKite
+# * Uploads Coverage reports to CodeCov
+# * Uploads Test Vectors reports to the SDK Report Runner
+# * Publishes (deploys) to TBD's Artifactory instance as version commit-$shortSHA-SNAPSHOT
+#
+# If triggered from workflow_dispatch, you may select a branch or tag to
+# deploy as an internal "release" (or SNAPSHOT, depending upon the version in the POM)
+# to TBD's Artifactory instance by not specifying a version.
 name: SDK Kotlin CI
 
 on:
   workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to publish. For example "1.0.0-SNAPSHOT". If not supplied, will default to version specified in the POM. Must end in "-SNAPSHOT".'
+        required: false
+        default: "0.0.0-SNAPSHOT"
   push:
     branches:
       - main
   pull_request:
     branches:
-      - "*"
+      - main
 
 jobs:
-  build:
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: [ubuntu-latest, macos-latest]
+  # On MacOS we only build, test, and verify
+  build-test-macos:
+    runs-on: macOS-latest
     steps:
       - uses: actions/checkout@v4
         with:
@@ -23,54 +39,120 @@ jobs:
       # https://cashapp.github.io/hermit/usage/ci/
       - name: Init Hermit
         uses: cashapp/activate-hermit@v1
+        with:
+          cache: true
+
+      - name: hash test inputs
+        run: |
+          if ! which sha256sum; then brew install coreutils; fi
+          sha256sum $(find test-vectors -name '*.json') > test-vector-hashes.txt
 
-      - uses: actions/cache@v3
+      - name: Build, Test, and Verify
+        run: |
+          # Maven "verify" lifecycle will build, test, and verify
+          mvn verify \
+              --batch-mode \
+              -P sign-artifacts
+        env:
+          SIGN_KEY_PASS: ${{ secrets.GPG_SECRET_PASSPHRASE }}
+          SIGN_KEY: ${{ secrets.GPG_SECRET_KEY }}
+
+  # On Ubuntu we build, test, verify, and deploy: Code Coverage, Test Vectors, and SNAPSHOT artifacts to TBD Artifactory
+  build-test-deploy-snapshot-ubuntu:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
         with:
-          path: ~/.gradle/caches
-          key: gradle-${{ runner.os }}-${{ hashFiles('**/*.gradle.kts') }}-${{ hashFiles('**/gradle/wrapper/gradle-wrapper.properties') }}-${{ hashFiles('**/versions.properties') }}
+          submodules: true
+
+      # https://cashapp.github.io/hermit/usage/ci/
+      - name: Init Hermit
+        uses: cashapp/activate-hermit@v1
+        with:
+          cache: true
 
       - name: hash test inputs
         run: |
           if ! which sha256sum; then brew install coreutils; fi
           sha256sum $(find test-vectors -name '*.json') > test-vector-hashes.txt
 
-      - name: Run Gradle Tasks
-        run: gradle build koverXmlReport
+      - name: Resolve Snapshot Version
+        id: resolve_version
+        run: |
+          # Version resolution: use provided
+          if [ -n "${{ github.event.inputs.version }}" ]; then
+            resolvedVersion=${{ github.event.inputs.version }}
+          # Otherwise, construct a version for deployment in form X.Y.Z-commit-$shortSHA-SNAPSHOT
+          else
+            longSHA=$(git rev-parse --verify HEAD)
+            shortSHA=$(echo "${longSHA:0:7}")
+            resolvedVersion="commit-$shortSHA-SNAPSHOT"
+            echo "Requesting deployment as version: $resolvedVersion"
+          fi
+
+          # Postcondition check; only allow this to proceed if we have a version ending in "-SNAPSHOT"
+          if [[ ! "$resolvedVersion" =~ -SNAPSHOT$ ]]; then
+            echo "Error: The version does not end with \"-SNAPSHOT\": $resolvedVersion"
+            exit 1
+          fi
+
+          echo "Resolved SNAPSHOT Version: $resolvedVersion"
+          echo "resolved_version=$resolvedVersion" >> $GITHUB_OUTPUT
+
+      - name: Build, Test, and Deploy to TBD Artifactory
+        run: |
+          # Set newly resolved version in POM config
+          mvn \
+            versions:set \
+            --batch-mode \
+            -DnewVersion=${{ steps.resolve_version.outputs.resolved_version }}
+
+          # Maven deploy lifecycle will build, run tests, verify, sign, and deploy
+          mvn \
+            deploy \
+              --batch-mode \
+              --settings .maven_settings.xml \
+              -P sign-artifacts
+        env:
+          ARTIFACTORY_USERNAME: ${{ secrets.ARTIFACTORY_USERNAME }}
+          ARTIFACTORY_PASSWORD: ${{ secrets.ARTIFACTORY_PASSWORD }}
+          SIGN_KEY_PASS: ${{ secrets.GPG_SECRET_PASSPHRASE }}
+          SIGN_KEY: ${{ secrets.GPG_SECRET_KEY }}
 
-      - uses: actions/upload-artifact@v3
+      - name: Upload Vector test results
+        uses: actions/upload-artifact@v3
         with:
           name: test-results
           path: |
-            **/build/test-results/test/*Web5TestVectors*.xml
+            **/target/surefire-reports/*TestVectors*.xml
             test-vector-hashes.txt
 
       - name: Upload coverage reports to Codecov
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           verbose: true
           flags: ${{ runner.os }}
 
-      - uses: actions/upload-artifact@v3
+      - name: Upload JUnit tests report
+        uses: actions/upload-artifact@v3
         with:
           name: tests-report-junit
           path: |
-            **/build/test-results/test/*.xml
+            **/target/surefire-reports/*.xml
 
       - name: Generate an access token to trigger downstream repo
         uses: actions/create-github-app-token@2986852ad836768dfea7781f31828eb3e17990fa # v1.6.2
         id: generate_token
-        # test only in main and report ubuntu results only
-        if: github.ref == 'refs/heads/main' && matrix.os == 'ubuntu-latest'
+        if: github.ref == 'refs/heads/main'
         with:
           app-id: ${{ secrets.CICD_ROBOT_GITHUB_APP_ID }}
           private-key: ${{ secrets.CICD_ROBOT_GITHUB_APP_PRIVATE_KEY }}
           owner: TBD54566975
           repositories: sdk-report-runner
 
       - name: Trigger sdk-report-runner report build
-        # test only in main and report ubuntu results only
-        if: github.ref == 'refs/heads/main' && matrix.os == 'ubuntu-latest'
+        if: github.ref == 'refs/heads/main'
         run: |
           curl -L \
           -H "Authorization: Bearer ${APP_TOKEN}" \
@@ -81,3 +163,14 @@ jobs:
           https://api.github.com/repos/TBD54566975/sdk-report-runner/actions/workflows/build-report.yaml/dispatches
         env:
           APP_TOKEN: ${{ steps.generate_token.outputs.token }}
+
+  # Ensure both MacOS and Ubuntu build/test jobs succeeded
+  confirm-successful-build-and-tests:
+    # Wait on both jobs to succeed
+    needs: [build-test-macos, build-test-deploy-snapshot-ubuntu]
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Log Success
+        run: |
+          echo "Builds for MacOS and Ubuntu succeeded."