Skip to content

Contributing

Source: github.com/pambrose/etcd-recipes. Licensed Apache 2.0.

Building

JDK 17 and the Gradle wrapper. make help lists every target.

make build         # ./gradlew clean build -x test
make tests         # full suite against a local etcd at localhost:2379
make tests-tc      # full suite against an ephemeral Testcontainers etcd (needs Docker)
make all-tests     # local, Testcontainers and multi-container variants in sequence
make tla           # model-check the TLA+ protocol specs in specs/ with TLC
make lint          # ./gradlew lintKotlin detekt
make zizmor        # audit the GitHub Actions workflows with zizmor
make api-check     # check the published public API against the api/ dumps
make api-dump      # update the api/ dumps after an intended API change
make coverage      # Kover HTML + XML + summary
make kdocs         # Dokka API docs
make versions      # dependencies with newer versions, and any that could not be checked
make versions-all  # the full dependency report, up-to-date ones included

make tests expects an etcd at http://localhost:2379:

./etcd-start.sh  # start          (or: make etcd-start)
./etcd-stop.sh   # graceful shutdown — SIGTERM, then SIGKILL after 10s

A single test class:

./gradlew :etcd-recipes-core:test --tests "io.etcd.recipes.barrier.DistributedBarrierTests"

Modules

Module Published as
etcd-recipes-core com.pambrose:etcd-recipes-core
etcd-recipes-jackson com.pambrose:etcd-recipes-jackson
etcd-recipes-micrometer com.pambrose:etcd-recipes-micrometer
etcd-recipes-spring-boot-starter com.pambrose:etcd-recipes-spring-boot-starter
etcd-recipes-ktor com.pambrose:etcd-recipes-ktor
etcd-recipes-examples — runnable examples
etcd-recipes-test-runners — test-only shadow JAR

Tests

Thread-based (*Tests.kt beside each recipe) — N threads in one JVM simulate distributed clients via blockingThreads(...) / nonblockingThreads(...) from TestExtensions.kt.

Container-based (container/Container*Test.kt) — each participant runs in its own container against a shared etcd container. Gated by assumeTrue(testcontainers=true), so a default ./gradlew check skips them.

Lincheck (*LincheckTests.kt) — Lincheck model-checks in-memory concurrent state for linearizability: the service provider strategies, and EtcdConnector's connection state and recorded exceptions. They run with the rest of the suite locally and need no etcd. CI leaves them out (-PskipLincheck): they're CPU-heavy, and on a 2-core runner they pushed the suite past its timeout. Reach for one when a change touches shared in-memory state that several threads update at once.

TLA+ specs (specs/) — the counted barrier's rounds, the read-write lock's admission, and the work queue's claims are specified in TLA+, modeling the code one RPC per action with leases expiring and responses lost between them. make tla runs TLC over every model (specs/tlc.sh fetches a pinned, checksum-verified TLC once, and needs only Java), and CI runs them on every pull request. A change to one of those protocols should update its spec; specs/README.md maps each spec to the code and lists what it checks.

Test JVMs fork per class (forkEvery = 1) so one spec's background threads and watch connections cannot bleed into the next. maxParallelForks lets classes run concurrently against one etcd, so each test namespaces its keys by class name. Keep doing that.

New Kotlin tests use Kotest with StringSpec() and an init {} block, plus MockK where it helps.

Adding a recipe

  1. Compose the existing extensions in common/ rather than reaching into jetcd directly.
  2. Extend EtcdConnector for anything stateful — it gives you the lifecycle, the exception list, connection state and close().
  3. Raise EtcdRecipeException / EtcdRecipeRuntimeException, not jetcd types.
  4. Add Kotest tests under etcd-recipes-core/src/test/kotlin/.
  5. Add a runnable example under etcd-recipes-examples/.
  6. Document it here, with a compiled snippet (below).

Documentation

This site is Zensical, under website/.

make site          # serve locally (wipes the previous build first)
make docs-check    # compile the snippets, then build in strict mode — what CI checks
make clean-site    # remove the generated site/ and .cache/
make check-site    # report outdated website dependencies (dry run)
make upgrade-site  # upgrade website dependencies, rewriting uv.lock

make site serves the site; make docs-check is the one that builds it, and it is what you want before pushing.

Code examples are compiled, not pasted

No example on this site is typed into a Markdown file. Every one is a real source file in a Gradle test source set, embedded at build time by pymdownx.snippets. ./gradlew compileTestKotlin compileTestJava type-checks all of them against the real API on every CI run, so an example cannot silently rot when the library changes.

They live in the module whose API they document:

etcd-recipes-core/src/test/kotlin/website/      Kotlin
etcd-recipes-core/src/test/java/website/        Java
etcd-recipes-<satellite>/src/test/…/website/<module>/

Why the satellites need their own

etcd-recipes-core's test source set cannot see the satellite modules — they depend on core, not the reverse. So Spring, Ktor, Jackson and Micrometer examples live in their own module's src/test, and zensical.toml lists each one in base_path.

Adding an example

Write a plain function that is never called, and mark the interesting part:

fun basicMutex(client: Client) {
  DistributedMutex(client, "/locks/orders").use { mutex ->
    mutex.withLock { /* ... */ }
  }
}

Then embed it:

=== "Kotlin"

    ```kotlin
    DistributedMutex(client, "/locks/orders").use { mutex ->
      mutex.withLock {
        // Only one client across the cluster runs this at a time.
        logger.info { "Critical section" }
      }
    }
    ```

=== "Java"

    ```java
    try (DistributedMutex mutex = new DistributedMutex(client, "/locks/orders")) {
      mutex.lock();
      try {
        // Only one client across the cluster runs this at a time.
        System.out.println("Critical section");
      } finally {
        mutex.unlock();
      }
    }
    ```

Run make docs-check and you are done.

Rules

  • They are not tests. No Kotest specs, no assertions, no main(). Plain functions, never invoked. They exist to be compiled.
  • Section names must match [a-z][-_0-9a-z]* — lowercase, digits, -, _. try-lock works; tryLock will not match, and the section silently will not render.
  • kotlinter and detekt lint them like any other source. Keep them small.
  • Prefer showing both languages. Coroutines are the honest exception.
  • A dangling snippet reference fails the build (check_paths = true) rather than rendering an empty block. That is deliberate — please keep it that way.

zensical must run from website/etcd-recipes

pymdownx.snippets resolves base_path against the process working directory, not against zensical.toml's location, so zensical build -f website/etcd-recipes/zensical.toml from the repo root finds no snippets. Every make target cds first.

Versioning

The library version lives in gradle.properties; Kotlin and dependency versions in gradle/libs.versions.toml. All modules share the one version.

Releasing bumps gradle.properties, moves the CHANGELOG.md [Unreleased] section under the new heading, adds a RELEASE_NOTES.md entry, and updates the coordinates quoted in the docs — the README download snippets plus several pages on this site. They are all literal version strings, so:

git grep -F '0.13.0'   # find every reference to the outgoing version

is the reliable way to catch them; do not rely on the list of files staying accurate.

make publish-maven-central then signs every module, publishes it, and releases it to Maven Central (make publish-snapshot publishes a -SNAPSHOT of the version instead). Both need GPG_SIGNING_KEY_ID naming a key in the local GPG keyring, and they read their secrets from the macOS keychain:

Keychain entry Account Holds
gradle-signing-password gpg-signing The signing key's passphrase
maven-central-username maven-central The name of a user token from central.sonatype.com
maven-central-password maven-central That token's password

The secrets reach only those two Gradle runs, as environment variables, never ~/.gradle/gradle.properties, which every Gradle build on the machine reads. Add the token once; -w with no value prompts for it, which keeps it out of the shell's history:

security add-generic-password -a maven-central -s maven-central-username -U -w
security add-generic-password -a maven-central -s maven-central-password -U -w

A missing or empty entry stops the target before Gradle starts, naming the entry but not its value.

CI

.github/workflows/ci.yml has two jobs:

  • TLA+ models — ./specs/tlc.sh, on every pull request and every push to master.
  • Build & test — detekt, then, on a pull request, only a compile of every main and test source set (the website's snippet sources included), lintKotlin, and checkKotlinAbi (the published API against the api/ dumps). A push to master runs the full suite instead, less the Lincheck checks: check koverXmlReport -PuseTestcontainers -PskipLincheck, with a coverage upload.

Pull-request CI does not run the tests

The Testcontainers suite takes 30+ minutes on a hosted runner, so a pull request is only compiled, linted, and API-checked. Run make tests-tc locally and see it pass before the PR merges; the full run on master is a check after the fact, not a gate.

check and koverXmlReport must stay in one Gradle invocation

Splitting them changes the -PuseTestcontainers input, which invalidates the test cache and makes the rerun hang against localhost:2379. The comments in ci.yml record this and the codecov report-path quirk — read them before editing.

.github/workflows/docs.yml builds the site on every PR. It deploys only after CI passes on a push to master, building the commit CI verified, so a site whose snippets no longer compile never goes out.

.github/workflows/zizmor.yml audits the workflows with zizmor on every pull request and push to master, and its Audit workflows job must pass before a PR can merge. make zizmor runs the same release locally. Every action is pinned to a commit SHA with its release in a trailing comment; Dependabot (.github/dependabot.yml) proposes the week's action updates in one PR, once a release is a week old. Gradle and website dependencies are updated by hand (make versions, make check-site).

.github/workflows/cleanup.yml prunes the Actions run list every Monday: cancelled and skipped runs after a week, and other runs after 30 days, when GitHub deletes their logs, keeping each workflow's newest 10 of those. Started by hand, it defaults to a dry run that only lists what it would delete. Keep its 30 days equal to the repository's log retention (Settings > Actions > General).