SDK compatibility, coverage, and release evidence

Run these commands from the repository root with JDK 21:

1
2
3
./gradlew build checkKotlinAbi
./gradlew koverXmlReport koverHtmlReport
./gradlew cyclonedxBom

Every Kotlin JVM and multiplatform module participates in ABI validation and coverage. Existing module coverage thresholds remain in effect. Merged coverage is a measurement, not a claim that every module has adequate tests. Review the uncovered branches before raising thresholds; never lower a threshold to make a failing change pass.

API changes

The api/ files describe the public binary surface. checkKotlinAbi rejects differences from these references and also runs through Gradle check. For an intentional API change, run ./gradlew updateKotlinAbi, review the generated diff, and include migration guidance for any incompatible change. Do not run the update task in CI: that would accept the regression instead of detecting it. An ABI reference is not an assertion of API quality or behavioral compatibility. Experimental APIs still need explicit stability guidance.

Dependency inventory and signing

Published -javadoc jars are generated by Dokka (javadoc format). Dokka only runs when a requested task name contains publish (for example publishAllPublicationsToReleaseStagingRepository or publishToMavenLocal) or with -Ptrustweave.dokka=true; ordinary builds produce an empty javadoc jar to stay fast.

cyclonedxDirectBom produces a module dependency inventory. Maven publications attach that module’s JSON inventory with the cyclonedx classifier. The root cyclonedxBom aggregates inventories for the repository; it describes the combined SDK, not an individual artifact. SBOMs record dependencies and do not establish that they are safe.

Remote Maven publication requires TRUSTWEAVE_SIGNING_KEY, an ASCII-armored private PGP key, and optionally TRUSTWEAVE_SIGNING_PASSWORD for a protected key. Configure these through the release runner’s secret store. Never place key material in Gradle properties committed to Git. publishToMavenLocal supports unsigned local development. Repository credentials and publication destinations remain release-owner configuration.

The Release evidence workflow (.github/workflows/release-evidence.yml) has three jobs:

  1. evidence builds and validates the tagged revision (or the selected revision for a manual run) and uploads the validation manifest, JARs and inventories. A v* tag must be an ancestor of origin/main. It publishes nothing and holds no attestation permission.
  2. publish (tags only, behind the maven-central environment approval) builds and signs once into build/release-staging, checks that every staged JAR is byte-identical to the one evidence validated, writes SHA256SUMS (including the aggregate SBOM), attests every file and SHA256SUMS itself, and only as its last step uploads that same directory to the Central Portal (USER_MANAGED, so a person still releases the deployment there).
  3. release-assets attaches SHA256SUMS and the aggregate SBOM to the GitHub release for the tag.

A configured workflow is not evidence of a successful release: retain the actual run. To verify a downloaded artifact, follow “Verifying a Release” in SECURITY.md, which covers checking the download against SHA256SUMS and gh attestation verify.

Module reports are under the root build/<module-path>/reports/ directory; root reports are under build/reports/. On Windows, this repository normally redirects build outputs to %LOCALAPPDATA%/TrustWeave/gradle-build/trustweave/; root reports use _root.

References: Kotlin ABI validation, Kover, CycloneDX Gradle plugin, GitHub attestations.


This site uses Just the Docs, a documentation theme for Jekyll.