# 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

```bash
./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`.