RFC Index & Process
Proposed process, not yet adopted
The repository contains no RFC process document, and no RFCs exist yet. This page defines a
lightweight process for review. Until the team adopts it (for example by referencing it from
CONTRIBUTING.md), treat it as a proposal, and treat the index below as empty.
An RFC (request for comments) is a written proposal opened before a consequential change is built, so that affected owners can object cheaply. Once a proposal is decided, its outcome is recorded as an ADR; the RFC stays as the discussion record.
RFC index
| RFC | Title | Status | Author | Outcome |
|---|---|---|---|---|
| RFC-0000 | Template (not a proposal) | template | n/a | Copy this to start a new RFC |
| No RFCs have been filed. | ||||
RFC or ADR?
| RFC | ADR | |
|---|---|---|
| Purpose | Ask for review of a proposal that is not yet decided | Record a decision that has been made |
| Written | Before implementation | At decision time, or afterwards to capture what already exists |
| Mutability | Edited freely while open; frozen when closed | Append-only after acceptance (dated clarifications and supersession links) |
| Skip it when | The change is reversible, local to one module, and touches no other owner's files | The choice is reversible implementation detail |
When to write an RFC
- A change that crosses module or service boundaries owned by different maintainers (see
.github/CODEOWNERS), when it is more than a one-line dependency. - Anything that would meet the ADR tests (hard to reverse, crosses service boundaries, taught by an incident) and where more than one viable design exists.
- Changes to shared infrastructure, tenancy, authentication or secret handling, where the cost of a wrong guess is an outage or a data exposure.
Lifecycle
| State | Meaning |
|---|---|
| draft | The author is still writing; not ready for comments. |
| open | Announced for review. Set a review deadline in the header. |
| accepted | Approved to build. Link the implementing work and, where the decision is architectural, the new ADR. |
| rejected / withdrawn | Closed without implementation. Keep the page and record why. |
| implemented | Shipped. Verification state must be stated exactly: compiled, tested, deployed to staging, or deployed to production are different claims. |
Process
- Number it. Take the next free number; numbers are never reused. Copy RFC-0000 Template to
rfc-NNNN-short-slug.html. - Fill the header and sections: Summary, Motivation, Detailed design, Alternatives, Risks, Rollout, Open questions. Cite repo paths for every claim about existing behaviour.
- Announce it. Add the row to the index above and a nav entry in
assets/js/site.jsunder therfcsection; open a GitHub issue or discussion linking to it. - Review. Owners of affected scopes comment until the deadline. Record objections and how they were resolved in the page, not only in chat.
- Decide. The owner of the affected area (per
CODEOWNERS), or the maintainers where ownership is unclear, accept or reject. Set the status and date. - Close the loop. On acceptance, write or update the ADR; on implementation, update the RFC with what actually shipped.
Constraints that apply to every RFC
A proposal must respect the standing deployment rules (see Conventions):
production and staging stay distinct; no browser-facing URL points at localhost; and no rollout step may
stop, delete or power-cycle production. An RFC that needs such an action must say so and leave the
decision to a human.