RFCs / 0001
Request for comments
Writing an idea down makes me think it through. It also lets other people read it, question it and come back to it later. An RFC, a request for comments, is how I do that for the platform I run and for the work around it.
When to write one
Write an RFC when a decision is hard to undo, when it changes how other people work, or when its reasons will matter later. A new service, a change to how people sign in, a change to how data is kept and a new way of working for a team are all good candidates.
A small fix does not need one. When in doubt, write a short one. One page is enough.
What goes in it
- The problem, and why it needs solving now.
- The background a reader needs.
- The options, with what each one costs and what it gives.
- The choice, and the reasons for it.
- The open questions and the risks.
Write down why, and not only what. A reader a year from now uses the reasons to decide whether the choice still holds.
How an RFC moves
- A draft starts in the wiki. The people it affects can read it there and comment next to the text. Drafts are private.
- When the draft is ready, it gets the next free number and comes here with
the status
discussion. The discussion stays in the wiki, and the RFC links to it. - When the discussion settles, the status becomes
published, and the RFC is a reference. - If we decide to do what it proposes, the status becomes
accepted. - If we stop pursuing it, the status becomes
abandoned. It stays here, because its reasons are still worth reading.
Numbers and replacements
An RFC keeps its number for good, and the number is its address. This one is rfc.starostka.io/0001, so a new title does not break a link. An RFC can still
be corrected after it is published, and its updated date says when.
When a new RFC takes over from an old one, the old one says “Replaced by” and links to the new one. The new one lists what it replaces.
Who can read them
Every RFC on this site is public. Work that cannot be public, such as security details or other people’s information, stays in the wiki.