From 02e17aa538e0a67b3059622a710f646ff312d5d9 Mon Sep 17 00:00:00 2001 From: Mattt Date: Wed, 16 Sep 2026 13:25:47 +0100 Subject: [PATCH 1/3] feat(docs): improve CONTRIBUTING.md, point example at published app --- CONTRIBUTING.md | 85 ++++++++++++++++++++++-- examples/offline-encrypt/README.md | 13 ++-- examples/offline-encrypt/build.gradle | 2 +- examples/offline-encrypt/settings.gradle | 2 +- 4 files changed, 90 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6dea316..fb44ca1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,14 +2,87 @@ # Contributing -Bug reports and pull requests are welcome on GitHub at https://github.com/evervault/evervault-java/issues. +Bug reports and pull requests are welcome on the [GitHub issue tracker](https://github.com/evervault/evervault-java/issues). -## Commit Formatting & Releases +## Building and testing -We use [changesets](https://github.com/changesets/changesets) to version manage in this repo. +The SDK lives in `lib/`. Use the Gradle wrapper: -When creating a pr that needs to be rolled into a version release, do `npx changeset`, select the level of the version bump required and describe the changes for the change logs. DO NOT select major for releasing breaking changes without team approval. +```sh +./gradlew build +./gradlew test +``` -To release: +`build` runs the test task, so the credentials note below applies to it too. -Merge the version PR that the changeset bot created to bump the version numbers. This will bump the versions of the packages, create a git tag for the release, and release the new version to npm. \ No newline at end of file +### Tests that need credentials + +The suite has 139 unit tests plus four end-to-end classes under `com.evervault.EndToEndTests` +that call the Evervault API. Without credentials, those four fail at initialization instead of +being skipped, so a clean checkout reports a red build: + +``` +EncryptTest > initializationError FAILED +143 tests completed, 4 failed +``` + +Either supply credentials: + +```sh +TEST_EV_APP_ID=app_xxx TEST_EV_API_KEY=ev:key:... ./gradlew test +``` + +or run the unit tests alone: + +```sh +./gradlew test --tests 'com.evervault.When*' +``` + +### Java compatibility + +`lib` targets Java 8 source and target compatibility, and CI runs the suite on 8, 11, 16, 17, +and 21. Code that only compiles on a later JDK will pass locally but fail in CI. + +To reproduce a specific version you need that JDK installed locally. Toolchain +auto-provisioning is not configured, so the build fails with "No matching toolchains" if it +is missing: + +```sh +./gradlew test -PjavaToolchainVersion=8 +``` + +### Dependency locking + +All configurations are locked. Adding, removing, or upgrading a dependency requires +regenerating the lockfiles, or resolution fails: + +```sh +./gradlew dependencies --write-locks +``` + +Commit the resulting `lib/gradle.lockfile` and `buildscript-gradle.lockfile`. + +## Examples + +`examples/` holds standalone projects that build against the published artifact and share the +repository's Gradle wrapper. When changing public API, check the examples still compile, and +uncomment `includeBuild('../..')` in the example's `settings.gradle` to build it against your +working tree. + +## Changesets and releases + +We use [changesets](https://github.com/changesets/changesets) to manage versions. + +A PR that should land in a release needs a changeset. Run `pnpm changeset`, pick the bump +level, and describe the change for the changelog. Do not pick major for a breaking change +without team approval. + +Releasing is two steps, both on `master`: + +1. Merging a PR that contains changesets prompts the bot to open a "New Release" PR that + bumps the version in `package.json` and `lib/build.gradle`. +2. Merging that PR tags the commit, creates the GitHub release, and stages the artifact to + Sonatype. Publishing to Maven Central then waits on manual approval of the `maven-central` + deployment environment. Until someone approves it, the release is staged but not public. + +After approval the artifact appears at `com.evervault:lib:` on Maven Central. diff --git a/examples/offline-encrypt/README.md b/examples/offline-encrypt/README.md index da3953d..dd22ca7 100644 --- a/examples/offline-encrypt/README.md +++ b/examples/offline-encrypt/README.md @@ -16,10 +16,15 @@ Evervault evervault = Evervault.withKey(appId, apiKey, key, teamUuid); `kid` is enforced when present - use `EvervaultKey.fromJwks(jwksJson)` if the JWK has no `kid`. -Built against the SDK in this repository via `includeBuild('../..')`, using the -repository's Gradle wrapper rather than carrying its own. +The example builds against the published SDK from Maven Central (see `build.gradle` for the +version) and uses the repository's Gradle wrapper rather than shipping its own. -## 1. Download your app's keys +For local SDK development, uncomment `includeBuild('../..')` in `settings.gradle` to +build against the working tree instead of the published artifact. Gradle substitutes +`com.evervault:lib` by group and module, so the version in `build.gradle` is ignored while +it is on. + +## 1. Download your App's keys ```sh mkdir -p keys @@ -58,5 +63,5 @@ EV_APP_ID=app_xxx EV_API_KEY=ev:key:... ../../gradlew run --args="" | --- | --- | --- | | `EV_KEY_ID` | — | `kid` to use, unless the JWKS holds a single key | | `EV_JWKS_PATH` | `keys/jwks.json` | JWKS to read | -| `EV_APP_ID` | `app_offline_example` | Evervault App whose credentials decrypt the ciphertext. Must be the app the JWKS came from | +| `EV_APP_ID` | `app_offline_example` | Evervault App whose credentials decrypt the ciphertext. Must be the App the JWKS came from | | `EV_API_KEY` | — | When set, the example also decrypts via HTTP call | diff --git a/examples/offline-encrypt/build.gradle b/examples/offline-encrypt/build.gradle index 4310114..dd4e0cf 100644 --- a/examples/offline-encrypt/build.gradle +++ b/examples/offline-encrypt/build.gradle @@ -7,7 +7,7 @@ repositories { } dependencies { - implementation 'com.evervault:lib:4.2.0' + implementation 'com.evervault:lib:4.3.1' } java { diff --git a/examples/offline-encrypt/settings.gradle b/examples/offline-encrypt/settings.gradle index 68e5910..b145890 100644 --- a/examples/offline-encrypt/settings.gradle +++ b/examples/offline-encrypt/settings.gradle @@ -1,3 +1,3 @@ rootProject.name = 'offline-encrypt' -includeBuild('../..') +// includeBuild('../..') From dc6f218a0bf22491b7bb4473b383d4535fd7190a Mon Sep 17 00:00:00 2001 From: Mattt Date: Wed, 16 Sep 2026 14:17:20 +0100 Subject: [PATCH 2/3] feat(docs): tidy sections from PR feedback --- CONTRIBUTING.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fb44ca1..554198b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,10 +40,7 @@ or run the unit tests alone: ### Java compatibility -`lib` targets Java 8 source and target compatibility, and CI runs the suite on 8, 11, 16, 17, -and 21. Code that only compiles on a later JDK will pass locally but fail in CI. - -To reproduce a specific version you need that JDK installed locally. Toolchain +Reproducing a specific CI Java version needs that JDK installed locally. Toolchain auto-provisioning is not configured, so the build fails with "No matching toolchains" if it is missing: @@ -62,13 +59,6 @@ regenerating the lockfiles, or resolution fails: Commit the resulting `lib/gradle.lockfile` and `buildscript-gradle.lockfile`. -## Examples - -`examples/` holds standalone projects that build against the published artifact and share the -repository's Gradle wrapper. When changing public API, check the examples still compile, and -uncomment `includeBuild('../..')` in the example's `settings.gradle` to build it against your -working tree. - ## Changesets and releases We use [changesets](https://github.com/changesets/changesets) to manage versions. From 81a584e13b825bf0981b5db50552de591c9925f6 Mon Sep 17 00:00:00 2001 From: Mattt Date: Thu, 17 Sep 2026 13:14:48 +0100 Subject: [PATCH 3/3] add comment for local build testing examples --- examples/offline-encrypt/settings.gradle | 1 + 1 file changed, 1 insertion(+) diff --git a/examples/offline-encrypt/settings.gradle b/examples/offline-encrypt/settings.gradle index b145890..473ddc5 100644 --- a/examples/offline-encrypt/settings.gradle +++ b/examples/offline-encrypt/settings.gradle @@ -1,3 +1,4 @@ rootProject.name = 'offline-encrypt' +// Uncomment this line to use a local build when testing // includeBuild('../..')