Venom
/SpecDocs
venom-specspec

The RFC process

venom-spec/PROCESS.md @ 81e1242

Every decision that crosses a repo boundary is written down here as an RFC before code depends on it: protocols, formats, the agent contract, policies. GitHub issues track the work; the RFC is the record of what was decided and why.

States

Draft ──► Accepted ──► Implemented ──► Superseded
  │           │                            ▲
  │           └────────────────────────────┘
  └──► (closed: PR closed without merging)
State Meaning Who sets it
Draft Proposed and open for review. It can change freely. Code MAY prototype against it, but nothing ships that depends on it. The author, when the RFC is created
Accepted The design is agreed. Implementations build against it, and it changes only as described in “Changing an RFC” below. The maintainer only. Agents never set this.
Implemented At least one shipped implementation follows it, and the RFC says which (repo and version or commit). For protocols, a conformance check exists (for example venom-echo, COM-216). The maintainer, or the author with the maintainer’s approval in the PR
Superseded Replaced by a newer RFC. The text stays for history, and the header points at the replacement. Set in the same PR that accepts the replacement

An RFC can go from Accepted straight to Superseded if it’s replaced before anyone implements it.

Proposing an RFC

  1. Open or find the issue in this repo, in the Venom OS project. The issue title starts with the RFC number, e.g. RFC-0002: Wire protocol ….
  2. Branch as <n>-<short-slug>, where <n> is the issue number.
  3. Copy the template: cp rfcs/0000-template.md rfcs/NNNN-short-title.md. Use lowercase words joined by hyphens for the short title.
  4. Write it. Fill every section of the template. Lead with concrete examples (byte traces, ZON snippets, CLI sessions); the prose explains them.
  5. Add it to the index in README.md, with status Draft.
  6. Open a PR titled GH-<n>: RFC-NNNN <title> with Fixes #<n> in the body, and set the issue’s Project Status to In Review.
  7. Review. Discussion happens on the PR. Record decisions in the RFC text, not only in comments. Answer or defer every Open question.
  8. Merge as Draft. A reviewed RFC can be merged with status Draft so other RFCs and issues can link to it.
  9. Acceptance. The maintainer sets the status to Accepted, either in the review PR or in a separate one-line PR. The README index changes in the same commit.

Numbering

  • RFCs are numbered with four digits, starting at 0001. 0000 is the template.
  • Numbers are reserved when the issue is created (the number goes in the issue title), and the README index lists reserved numbers under “Planned”. Take the next number after the highest one in the index.
  • A number is never reused, even if the RFC is closed without merging.

Changing an RFC

  • Draft: change anything, in any PR.
  • Accepted or Implemented:
    • Editorial changes (typos, clearer wording, extra examples that don’t change behaviour) go in a normal PR.
    • Normative changes (anything an implementation would have to change for) need a new RFC that supersedes the old one, or, for a small compatible addition, a PR the maintainer explicitly accepts. Either way, add a line to the RFC’s header or a “History” section saying what changed and when.
  • Superseded: frozen, apart from fixing the “Superseded by” link.

Normative language

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY and OPTIONAL in RFCs are interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in capitals.

Checks before merging

  • Every relative link in the changed files resolves.
  • Examples are copy-pasteable: no $ prompts inside code meant for pasting into a file, and JSON and ZON in examples parse.
  • The README index matches the files in rfcs/ and their status headers.