Technical design docs and RFCs

Play this lesson

Request for comments

On 7 April 1969, Steve Crocker at UCLA wrote "Request for Comments: 1", titled Host Software. It described how computers on ARPANET, the network that grew into the internet, would talk to each other.

Calling it a request for comments (RFC) meant: this is not final, tell us what is wrong. Internet standards are still published as numbered RFCs.

How Rust uses RFCs

The Rust programming language uses RFCs for big changes. Each one goes through these steps:

Quick check

Why does Rust's final comment period last ten calendar days?

  1. So it is open for at least 5 business days, whatever the week looks like
  2. Because a law requires ten days
  3. So the author has time to rewrite the language
Show the answer

So it is open for at least 5 business days, whatever the week looks like

Rust's RFC page says the period lasts ten calendar days "so that it is open for at least 5 business days". Everyone gets a fair chance to object.

What does not need one

Rust's rules say bug fixes, documentation, and rewording or reorganising that does not change meaning go through normal pull requests. RFCs are for changes people will notice and argue about.

That matches the design doc rule: write one only when there are real choices to make.

Design doc or RFC?

A design doc plans one piece of our own game. An RFC proposes a change to something many people share: a language, a protocol, or the studio's shared rules.

Kai wants every Shard Garden server to write logs in one format. That changes every team's work, so Kai writes an RFC: posted, open for comments for a fixed time, then decided.

Quick check

Once an RFC is accepted, the change is guaranteed to ship.

Show the answer

False

Rust's process says an accepted RFC may be built, but acceptance does not promise the feature will be merged.

Pick the process

Which change should Kai put through an RFC?

  1. Changing how every team names its analytics events
  2. Fixing a typo in the settings menu
  3. Making one button 2 pixels wider
Show the answer

Changing how every team names its analytics events

Event names are shared by every team and every dashboard, so everyone should get a say. The other two are small fixes for a normal pull request.

Proposals that last

A closed RFC still teaches: it records the idea, the arguments and why it was turned down. When someone suggests the same change two years later, the team links the old discussion instead of having it again.

Bolt says: Next: decision records, the short notes that remember why.

Fact-checked 12 October 2026