2.4 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

./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 and creates missing fixtures. It never overwrites existing fixtures unless -force is given, which is reserved for specification changes.

Commits and releases

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

2.4 KiB Raw Blame History