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.
78 lines
3.2 KiB
78 lines
3.2 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
|
|
|
|
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`.
|