Contributing

Vela is small enough that contributors can hold the whole protocol in their head. The bar for a change is high; the path to making one is short. Specifications change via RFC. Reducer implementations, test vectors, and operator tooling can land without an RFC if they hold the conformance line.

§1 What the project accepts

Four tracks of contribution. The first three target the protocol itself; the fourth targets the operator ecosystem around it.

1. 01

   Reducer implementations

   Conformant reducers in any language. Track the public test-vector suite; publish your conformance number with every release. New official bindings can be proposed via RFC.

2. 02

   Spec changes

   Type primitives, event kinds, mutation rules. These require an RFC. Wire-compatible changes land in minor versions; breaking changes wait for the next major.

3. 03

   Test vectors

   Vectors covering edge cases the suite misses today. Each vector is a small JSON object pairing an event with the expected state mutation. PRs welcome without an RFC.

4. 04

   Operator and witness tooling

   Anything that helps a new operator stand up a reducer + transparency-log mirror. Documentation, deployment recipes, monitoring. Lives in the ops/ directory.

§2 The RFC process

Anything that changes the wire-level protocol, the mutation rules, or a normative keyword in the spec needs an RFC. The process is:

1. 01 Open a draft PR against rfcs/ with the proposal as a new markdown file. Use the template at rfcs/0000-template.md.
2. 02 Discussion happens on the PR. The author folds feedback into the document; the diff history is the discussion record.
3. 03 When the RFC is accepted, an editor assigns it a number and merges it. Implementation lands in a separate PR that adds test vectors and updates each reducer to pass them.
4. 04 The change ships in the next minor version. The changelog entry cites the RFC by number.

§3 License and stewardship

Vela is dual-licensed Apache-2.0 OR MIT. Contributors certify their work under the Developer Certificate of Origin; sign your commits with git commit -s.

Stewardship is held by a small group of editors who maintain the spec and review RFCs. The current editors are listed in MAINTAINERS.md; the goal is to broaden this group as more institutions begin running reducers and witnessing. Editors are explicitly not privileged at the protocol level; the witness set is what arbitrates state, not the editor list.