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:
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¶
- Compose the existing extensions in
common/rather than reaching into jetcd directly. - Extend
EtcdConnectorfor anything stateful — it gives you the lifecycle, the exception list, connection state andclose(). - Raise
EtcdRecipeException/EtcdRecipeRuntimeException, not jetcd types. - Add Kotest tests under
etcd-recipes-core/src/test/kotlin/. - Add a runnable example under
etcd-recipes-examples/. - 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-lockworks;tryLockwill 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:
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 tomaster. - 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, andcheckKotlinAbi(the published API against theapi/dumps). A push tomasterruns 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).