rfc implementation

Pre-Alpha. This page describes behavior that may change.

Ze implements a lot of RFCs. Implementing an RFC in Ze is not a matter of "read the RFC and write the code". It is a matter of tracking which RFCs the project depends on, recording what has been implemented and what has not, and making sure the implementation stays aligned with the RFC text over time. This page covers how that process works.

The canonical rule file is .claude/rules/rfc-compliance.md in the repo. This page summarises it.

Where RFCs live

RFCs tracked by Ze live under main/rfc/ in the repo.

main/rfc/
├── README.md           # Master index of tracked RFCs with status
├── short/              # Short extracts of load-bearing RFC sections
├── drafts/             # Draft RFC tracking
├── full/               # Full RFC text references
└── ...

The master index lists every RFC the project cares about, its current implementation status (complete, partial, not started), and the location of the relevant code. The short extracts are compressed versions of the RFC sections that the code actually depends on, so cross-checking a claim against the RFC does not require re-reading the full document.

The implementation process

Every RFC implementation in Ze follows the same five steps.

1. Spec. Before any code is written, the maintainer drafts a spec under plan/ that names the RFC, lists the sections being implemented, and defines the acceptance criteria. The spec explicitly calls out what is out of scope. Specs are written from plan/TEMPLATE.md.

2. Short extract. If the RFC has load-bearing sections that the code will reference (wire formats, validation rules, state machine transitions), the sections are extracted into rfc/short/<rfc>.md. The extract is a compression, not a summary: it preserves the exact text of the parts that matter.

3. TDD implementation. The tests come first. Every test is tied to a specific RFC section, either by name in the test function or in a comment. This is how RFC compliance stays visible in the test suite.

4. Code. The implementation goes in the appropriate component. Every non-trivial decision cites the RFC section in the code comment: // RFC 4271 §9.1.2.2: route selection and so on. This is what lets reviewers verify the code against the RFC without reading both cover to cover.

5. Register in rfc/README.md. Once the implementation lands, the master index is updated. The RFC moves from "not started" or "partial" to "complete", the location of the code is recorded, and any deviations from the RFC are documented explicitly.

What "complete" means

A Ze RFC implementation is complete when:

• Every mandatory section of the RFC is implemented.
• Every mandatory section has at least one test.
• Any deviations from the RFC (intentional or otherwise) are documented in the master index.
• Interop tests against at least one other implementation pass.
• The implementation is referenced from the in-tree docs.

"Complete" is a status in the index, not an opinion. Partial implementations that cover only a subset of the RFC are explicitly recorded as "partial", with the covered subset listed.

Deviations from RFCs

Ze deviates from RFCs in a small number of cases, and every deviation is documented in docs/exabgp/exabgp-differences.md or in the relevant in-tree architecture doc. Two examples.

Attribute ordering in UPDATE messages. The RFC does not mandate an ordering; Ze adds attributes in RFC 4271 section 5 description order, then optional attributes. The resulting wire bytes differ from ExaBGP (which sorts by type code) but both are compliant.

Neighbor qualifier syntax for multi-session targeting. ExaBGP supports per-session targeting through qualifiers on the neighbor keyword. Ze does not: commands apply to every session matching the peer IP. This is an API deviation, not a protocol deviation, but it is documented for the same reason.

Deviations that are not documented are bugs.

Cross-checking an implementation against an RFC

When you need to verify that a piece of Ze code matches what the RFC says, the process is:

1. Find the short extract under rfc/short/<rfc>.md.
2. Cross-reference with the code comments that cite the section.
3. Read the tests that target the section.
4. If anything is missing or unclear, read the full RFC section.

The short extract plus the code comments plus the tests should be enough for most reviews. The full RFC is a fallback.

When a new RFC appears

Step zero of implementing a new RFC in Ze is to add it to rfc/README.md as "not started", before any spec is written. This serves two purposes. It makes the RFC visible in the project inventory (make ze-inventory reads the index), and it forces the question "is this RFC actually worth implementing in Ze" to be answered explicitly.

Not every RFC makes it past this step. If the answer is "no, not yet", the RFC stays in the index as "not started" with a rationale, and the project has a documented reason.

The /ze-rfc command

Claude Code has a project-specific slash command, /ze-rfc, that generates an implementation summary from an RFC. It is not a code generator; it is a planning aid that turns an RFC into a list of spec items. The summary is a starting point for the human-written spec in step 1.

See also

• Contributing for the spec-first contribution workflow.
• Coding standards for the TDD rule.
• Claude Code for the slash commands.
• main/rfc/README.md and main/.claude/rules/rfc-compliance.md for the canonical rules.