Contributing¶
Thanks for looking. This SDK is a thin client: it sends requests to the
Crypto Service REST API (crypto-server) and maps the responses to Java
records. The cryptography lives in the server, in
crypto-service;
change it there.
Before you open a pull request¶
Everything CI checks you can run locally with a JDK 17 or newer;
./mvnw fetches the pinned Maven and checks its SHA-256:
make check
It runs the version check, the whitespace and size gates, mvn -B
verify (unit tests against loopback stub servers, fuzz seeds, JaCoCo at
100 %, PMD) and compiles the examples and README snippets.
To run the conformance kit, start crypto-server with an API key and a JWT secret (synthetic values) and point the runner at it:
make conformance
with CRYPTO_SERVICE_URL, CRYPTO_SERVICE_API_KEY and
CRYPTO_SERVICE_JWT_SECRET set. make regression does all of it for
you: it builds the pinned server, starts it on a loopback port with
random credentials and runs every live check.
Maven refuses any dependency or plugin whose SHA-256 is not recorded in
.mvn/checksums/. After changing a version, including a Dependabot
bump, run make lock and commit the diff with the change.
Coding style¶
The project follows the
Google Java Style Guide.
Layout is not a matter of taste here: every Java file (library, tests,
fuzz targets, benchmarks and examples) must be exactly what
google-java-format writes, the version bundled with the pinned
fmt-maven-plugin in pom.xml. make format rewrites the files and
make style checks them; CI's Lint and format job runs make style.
On top of the guide, the build enforces:
- no tabs, trailing spaces or CRLF, a final newline, and at most 100
columns in the library and examples (
make format-check,.editorconfig); - at most 500 lines per Java file (
make size); javac -Xlint:all -Werror: a new compiler warning fails the build;- PMD ceilings per method: cyclomatic complexity 10, cognitive
complexity 15, 60 statements (
config/pmd/complexity.xml); - Javadoc on every public type and member, checked by doclint
allwith warnings as errors (make javadoc).
The parts of the guide no tool checks (naming, the order of members,
Javadoc wording) are checked in review. The rules that are particular
to this SDK, such as no cryptography in src/main and no secrets in
any message or toString, are in AGENTS.md.
Updating the server contract¶
- Put the new crypto-service commit SHA in
ci/server.ref. - Copy that commit's
conformance/directory here unchanged. - Compare its
openapi/crypto-service.openapi.yamlwith the records and operations; add or change them with tests. - Run
make regression.
The README demo¶
.github/demo.gif is rendered from .github/demo.tape by make demo
with vhs, against a server at
CRYPTO_SERVICE_URL; never record it by hand.
Code review¶
Every change reaches main through a pull request: topic branches merge
into the release branch feat/v<next-version>, and its one pull request
merges into main. Branch protection on main requires signed commits,
forbids force-pushes and deletion, applies to administrators too, and
requires these checks to pass: Lint and format, Build, unit tests and
coverage (Java 17 and 21), Benchmarks smoke run, API breakage,
Conformance against crypto-server, both CodeQL analyses, Fuzz
ProblemFuzzTest and ResponseDecodingFuzzTest, the dependency audit, the
manual build, markdownlint, codespell, REUSE, links and Signed-off-by
on every commit. The other jobs (Fuzz RetryAfterFuzzTest, Reproducible
build) run on every pull request too, and a red one blocks
the merge by the maintainer's rule rather than by the setting.
What a reviewer checks¶
The checks CI cannot make, in this order:
- The change does what it says. Read the diff against the description and, for an API change, against the pinned OpenAPI document and the conformance kit.
- Tests. Behaviour changes come with tests in the same commit; a bug fix comes with a test the commit says was seen to fail without the fix (DEVELOPMENT.md).
- The thin-client and secrets rules in AGENTS.md: no
cryptography in
src/main, nothing secret in a message ortoString(a new record with secret members redacts them), no logging, synthetic data only. - Retry safety. A new route that creates or deletes server state is
in the
Routetable. - Compatibility. A change to the public API, to what is sent, or to
which exception an answer raises is called out in
CHANGELOG.md; japicmp catches the binary and source breaks. - Dependencies and CI. A new or bumped dependency or plugin comes
with
make lockand a reason; a workflow change keeps actions pinned by SHA, permissions minimal andpersist-credentials: false. - The assurance case. A change to a trust boundary, entry point or release step updates docs/ASSURANCE.md.
- Style and docs. Google Java Style (enforced), Javadoc on public API, documentation and changelog current.
A pull request is acceptable when every required check passes, every commit is signed off and signed, and the reviewer has no open question on the list above. A reviewer records what they checked in the review or the pull request; "LGTM" alone is not a review.
Review with a single maintainer¶
The project has one maintainer, Sebastien Rousseau
(GOVERNANCE.md). Pull requests from anyone else are
reviewed by the maintainer against the list above before merging. The
maintainer's own pull requests, including those written with AI
assistance, have no second human reviewer: the maintainer reviews the
diff against the same list, the pull request description says what was
run and observed, and the required checks must pass; the maintainer
then merges it himself. Branch protection therefore requires zero
approving reviews. This is self-review, not two-person review, and the
project does not claim otherwise. When a second maintainer joins,
main will require an approving review from someone other than the
author.
Commits and pull requests¶
- Conventional commits (
feat:,fix:,docs:,test:,build:,ci:,chore:), subject of at most 50 characters, body wrapped at 72 saying what and why. - Sign off every commit (
git commit -s, see DCO.txt); the DCO workflow checks every commit of a pull request. Commits tomainmust also carry a verified signature (SSH or GPG): setcommit.gpgsignand a signing key. The maintainer's keys are in KEYS.asc. - Pull requests go to the release branch
feat/v<next-version>, never tomaindirectly. - Synthetic data only: never commit real keys, tokens or plaintexts.