# RFC process

Address: https://nowa.im/cotty/handbook/rfc-process/  
Status: Draft  
Created: 2026-11-22

An RFC records one technical decision: what is proposed, why, and what was rejected. This page defines when an RFC is needed and how it moves from draft to accepted.

## What an RFC contains

RFCs are thin. An RFC holds the decision and its reasoning. It does not hold the normative text. The exact rules, formats and behavior are written in the state documents the RFC changes: architecture pages, specifications, handbook pages. Those changes belong to the same change set as the RFC.

A reader who wants to know what cotty does reads the state documents. A reader who wants to know why reads the RFC.

The skeleton is in [Templates](https://nowa.im/cotty/handbook/templates/#rfc).

## When an RFC is required

Write an RFC when a decision:

- is hard to reverse;
- crosses a boundary that others depend on: a wire protocol, an on-disk format, a public API, the security model;
- shapes several parts of the system at once;
- changes how the project works.

No RFC is needed to fix an error, to clarify wording without changing meaning, or to change details inside one component that do not change its documented behavior.

Product changes are not made by RFC. They go through a [version design](https://nowa.im/cotty/handbook/documentation/#version-design). An RFC names the product scenario it serves.

## Lifecycle

| Status | Meaning |
|---|---|
| `draft` | Being written. Not ready for a decision. |
| `discussion` | Complete, and waiting for a decision. |
| `accepted` | Decided. The state documents it affects are updated. |
| `implemented` | The code matches it. |
| `rejected` | Decided against. Kept as a record. |
| `withdrawn` | Dropped by its author. |
| `superseded` | Replaced by a later RFC, named in `superseded_by`. |

```mermaid
stateDiagram-v2
    [*] --> draft
    draft --> discussion
    discussion --> draft
    discussion --> accepted
    discussion --> rejected
    draft --> withdrawn
    discussion --> withdrawn
    accepted --> implemented
    accepted --> superseded
    implemented --> superseded
```

The project maintainer decides acceptance.

## A change set

A change set for an RFC contains:

1. The RFC, in both languages, under the next free number.
2. The changes to the state documents. The RFC lists those pages in `affects`. Each of those pages lists the RFC number in `rfcs`.

While the RFC is in `draft` or `discussion`, a state page that the RFC introduces has the status `draft`.

## Acceptance

An RFC can be accepted when:

- each open question is resolved, or is deferred with a stated reason;
- `affects` lists at least one page, and those pages contain the change;
- the checks pass.

On acceptance, the status becomes `accepted` in both languages, and the pages the RFC introduced become `accepted`.

## After acceptance

An accepted RFC is not rewritten. Only its status, its `superseded_by` field and plain errors change. To change a decision, write a new RFC that names the old one in `supersedes`.

Where a state document and an RFC disagree, the state document governs.

## Numbers

An RFC file is named `NNNN-slug.md`, with four digits. A number is never reused, including the numbers of rejected and withdrawn RFCs.
