# 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:

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

```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,
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`.