DateKeys/CONTRIBUTING.md

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

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.