You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
61 lines
2.4 KiB
61 lines
2.4 KiB
# 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`.
|