3.2 KiB

Raw Blame History

Contributing

Thank you for helping. This module is the reference implementation of a specification, so a few rules matter more than usual.

The specification decides

Code adds no semantics. If an implementation question reveals a gap or a problem in the specification, open an issue with a reproducible case: a failing test, a fixture, a mutation or a fuzzing input (spec §76).
Every change to normative code updates docs/traceability.md in the same pull request, and spec/datekeys.cddl when a schema is affected.
Official vectors and fixtures in testdata/ are frozen. Changing one needs a specification change first.

No cryptography of our own

Only age, tlock and drand's BLS verification. New cryptographic dependencies are not accepted without prior discussion.

Style

Identifiers, code comments, error messages and commit messages in English. User documentation in English with a Spanish version.
gofmt, goimports, go vet, staticcheck and golangci-lint (see .golangci.yml) must pass.
Package and function comments cite the section they implement, for example // Spec §26.
Every protocol failure wraps exactly one sentinel of errors.go with %w and context. Never replace an error with a more convenient one.
Parsers check limits before allocating, never panic on input, and have a fuzz target.
No mutable global state. The profile registry and the clock are passed explicitly; only cmd/datekeys reads the wall clock.
Secrets never appear in logs or String() output, and our own buffers are wiped when done.

Tests

The server runs no CI. The gate is scripts/check.sh, run by the versioned pre-push hook once you enable it in your clone:

git config core.hooksPath .githooks

Skip it only deliberately with git push --no-verify, and say why in the commit message. The workflows in .gitea/workflows are ready for a Gitea 1.21 or later with a runner; until then they do not run.

./scripts/check.sh                     # everything ci.yml runs, on any machine; run before pushing
go test -race ./...
FUZZ_PARALLEL=4 ./scripts/fuzz.sh 60s  # every parser; each worker uses a 100 MB temp file
go test -tags interop ./capsule        # needs the age and tle CLIs
go test -tags integration ./...        # live Quicknet

Coverage must stay at or above 90 % for codec, capsule, accesskey, datekey and agewrap.

Fixtures

go run ./internal/testkit/genfixtures -out testdata regenerates the vectors, the corpora and the frozen inspect outputs, and creates missing fixtures. It never overwrites existing fixtures unless -force (every fixture) or -only NAME[,NAME...] (the named ones) is given, which are reserved for specification changes. Prefer -only: every fixture it does not name keeps its exact bytes. The mutations built with age randomness keep the capsules recorded in testdata/vectors/mutations.json; -only mutations rebuilds them, which a change to one of those mutations needs. testdata/README.md documents every format and is updated with any change to one.

Commits and releases

Semantic versioning; v0.x until the specification reaches v1.0. Each release updates CHANGELOG.md.

3.2 KiB Raw Blame History