Contributing

How to propose a change to Ovrin: the setup, the commit conventions, and the questions review will ask, each tied to a numbered engineering rule.

Changes to Ovrin go through its repository, and the engineering standard is the numbered
rules — review enforces them.

What v1.0.0 changes for contributors

Ovrin is at v1.0.0, so the API is stable. A pull request that changes an exported signature has a high
bar to clear, because it would need a v2. Additions do not: a new field on a plain struct, or a new
option, can land in a minor release.

Core expectations

  • keep the core free of dependencies — not "few", zero
  • keep cgo out of the core entirely
  • never let document content reach an error, log line, trace or metric
  • preserve provider independence: adapters map a provider's API, they do not make decisions
  • write significant decisions down as an architecture decision record, including what they cost

Mechanics

  • run make check before opening a pull request — it is the same gate CI runs
  • write commits in the Conventional Commits style, on a type/slug branch
  • sign off every commit under the Developer Certificate of Origin
  • open an issue before contributing a new provider adapter

The most valuable contributions

The API is settled, but accuracy is still unmeasured. So the contributions that help most are:

  • real corpus documents the project is allowed to redistribute — the corpus today is synthetic
  • provider adapters, each with its silently-ignored behaviour documented
  • disagreement with an architecture decision record that is wrong

Because nobody outside the project has reported running Ovrin in production yet, bug reports from real
use are unusually valuable too.