Request for Comments (RFC) Template

What it is

A Request for Comments (RFC) is a formal proposal document used to gather structured feedback on a significant technical or process change before it is adopted. Originating from the IETF's internet standards process, the RFC format has been widely adopted by engineering teams at companies such as Rust, React, Ember, and many others as a mechanism for inclusive, deliberate decision-making on changes that affect broad audiences.

Unlike a Design Doc — which typically describes how a known solution will be implemented — an RFC often precedes the design phase and is used to validate the problem framing, explore the solution space collaboratively, and build community consensus. The RFC process is especially valuable when the change will impact multiple teams, require API or protocol changes, or introduce a new paradigm that engineers need to opt into.

An RFC is a living document during the comment period. It is numbered, tracked, and eventually either accepted (triggering downstream design and implementation work), withdrawn, or superseded. The archived corpus of accepted and rejected RFCs forms an invaluable record of the organization's technical reasoning over time.

Why it exists

Technical decisions that affect many people should involve many people. The RFC process provides a structured, asynchronous mechanism for soliciting that input without requiring endless meetings. It democratizes architectural input — anyone who reads the RFC and has a meaningful perspective can comment, regardless of their seniority or role.

RFCs also slow down decisions that should be slowed down. The comment period creates a forcing function that prevents well-intentioned but under-examined changes from being adopted prematurely. This is particularly important for public APIs, shared libraries, and platform contracts where reversing a decision after adoption is extremely costly.

Finally, the RFC record provides historical context for the organization's direction. When a new engineer asks "why does our framework work this way?", a well-archived RFC corpus provides a richer answer than any codebase can. It captures not just what was decided but what was proposed and rejected, and why — context that is otherwise lost within months of a decision being made.

When to use

• When proposing a breaking change to a public API, shared library, or platform contract that will require action from consumers.
• When introducing a new architectural pattern, tooling standard, or development practice that all teams in the organization will be expected to follow.
• When the problem or solution is genuinely uncertain and you need input from engineers outside your immediate team to explore the design space.
• When organizational buy-in is important — writing an RFC signals respect for stakeholders' expertise and gives them a formal channel to shape the outcome.
• When proposing deprecation or removal of a widely-used feature, system, or interface where affected parties need advance notice and migration guidance.

When NOT to use

• For decisions that affect only your team and have no cross-cutting impact — a Design Doc or ADR is more appropriate.
• When speed is critical and the change is low-risk; the RFC comment period (typically one to four weeks) adds timeline overhead that is not always justified.
• As a mechanism to generate the appearance of consensus for a decision that has already been made by leadership — this poisons the RFC process and destroys trust.
• For purely operational or infrastructure changes with no API or protocol impact, where a runbook or deployment plan is the right artifact.

Template

# RFC-[NUMBER]: [Short descriptive title]

**Author(s):** [Name], [Name]
**Status:** Draft | Request for Comments | Final Comment Period | Accepted | Withdrawn | Superseded
**Created:** [YYYY-MM-DD]
**Comment Period Ends:** [YYYY-MM-DD]  
**Tracking issue:** [Link to GitHub issue or Jira ticket where comments are collected]
**Supersedes:** [RFC-NNN if applicable]
**Superseded by:** [RFC-NNN if applicable]

---

## Abstract

[Concise description of what is being proposed and why it matters.]

---

## Motivation


### Current Situation
[Describe how things work today and the limitations of the current approach.]

### Problem
[Articulate the specific problem or limitation that this RFC addresses.
Include quantitative data if available: error counts, latency, developer
hours lost, number of teams affected.]

### Goals
* [Goal 1 — what this RFC aims to achieve]
* [Goal 2]
* [Goal 3]

### Non-Goals
* [What this RFC explicitly does not address]
* [Scope boundary to prevent misinterpretation]

---

## Detailed Design


### Overview
[High-level description of the proposed solution.]

### Specification

#### [Sub-topic 1 — e.g., "New API surface"]
```
[Code example, API signature, schema, or pseudocode]
```
[Explanation of the above]

#### [Sub-topic 2 — e.g., "Behavioral changes"]
[Describe changes to existing behavior. Call out breaking changes explicitly.]

#### [Sub-topic 3 — e.g., "Configuration"]
[Describe any new configuration options, flags, or environment variables.]

### Example

```
[Full working example demonstrating the proposed feature or change]
```

---

## Drawbacks

* [Drawback 1 — e.g., "Requires all consumers to update their clients within 6 months"]
* [Drawback 2 — e.g., "Adds complexity to the configuration model"]
* [Drawback 3 — e.g., "Performance overhead of N% in the hot path"]

---

## Alternatives


### Alternative 1: [Name]
[Describe the alternative.]

**Trade-offs / why not chosen:**
[Explanation of the specific limitation that ruled it out.]

### Alternative 2: [Name]
[Describe the alternative.]

**Trade-offs / why not chosen:**
[Explanation.]

### Do Nothing
[Describe the consequences of leaving the current situation unchanged.
This is always a valid alternative and should be addressed explicitly.]

---

## Adoption Strategy


### Breaking Change Assessment

[Classification and justification]

### Migration Path
[Step-by-step guide for how existing users migrate to the new approach.]

### Deprecation Timeline
| Phase | Date | Action |
|-------|------|--------|
| Announcement | [YYYY-MM-DD] | Old approach deprecated, migration guide published |
| Warning period | [YYYY-MM-DD] | Runtime warnings emitted for deprecated usage |
| Removal | [YYYY-MM-DD] | Old API/behavior removed |

---

## Unresolved Questions

| # | Question | Assigned to | Notes |
|---|----------|-------------|-------|
| 1 | [Open question] | [@name] | [Context] |
| 2 | [Open question] | [@name] | [Context] |

---

## References

* [Related RFC-NNN — title]
* [External reference — title and URL]
* [Issue or ticket link]

---

## Changelog
| Date | Author | Change |
|------|--------|--------|
| [YYYY-MM-DD] | [Name] | Initial draft |
| [YYYY-MM-DD] | [Name] | [Summary of revision] |

Pros and cons

Writing guidance

The Motivation section is where RFCs succeed or fail. Reviewers who do not feel the pain of the problem will not support the solution. Use concrete data: incident counts, latency numbers, lines of boilerplate code that engineers write repeatedly, or user complaints. If you cannot find data, consider whether the problem is as severe as you believe. A compelling motivation section makes reviewers eager to get to the solution rather than skeptical of it.

The Drawbacks section requires genuine honesty. Reviewers will find the drawbacks regardless; addressing them preemptively demonstrates rigor and builds trust. Paradoxically, a thorough drawbacks section often increases the RFC's acceptance rate because it signals that the author has done hard thinking about the costs, not just the benefits. If your drawbacks section is empty or consists of "no drawbacks identified," reviewers will fill it in themselves and may be harsher than you would have been.

Set a specific comment period end date and stick to it. Open-ended comment periods are a common failure mode — they feel inclusive but in practice lead to either indefinite delay or a sudden unilateral decision. Two to four weeks is typical for most organizational RFCs. Announce the Final Comment Period one week before it closes, summarize the key discussion threads, and give reviewers a final opportunity to raise blocking concerns before you move to acceptance.

Common mistakes

• No decision-maker identified: An RFC without a named person who will make the final acceptance call can languish for months with unresolved discussion threads.
• Skipping the Do Nothing alternative: "Do nothing" is always an option. Failing to address it suggests the author has not honestly evaluated the urgency of the change.
• Insufficient detail in the Adoption Strategy: Reviewers who will be impacted by a breaking change need a concrete migration path before they can assess the true cost of the proposal.
• Treating all comments as equal: Not all feedback carries the same weight. Maintainers should distinguish between blocking concerns, suggestions, and preferences — and communicate these distinctions clearly to avoid prolonged debates over non-critical points.

Review checklist

• Does the Motivation section include quantitative data or concrete examples of the problem?
• Is at least one "Do Nothing" alternative addressed in the Alternatives section?
• Is the comment period end date set and is there a named decision-maker for acceptance?
• Does the Adoption Strategy describe the migration path for existing users in step-by-step detail?
• Are all blocking Unresolved Questions assigned to specific owners with expected resolution dates?

Example usage

• Framework API change: The React team publishes RFC-0068 proposing Hooks, inviting community feedback on the API design and migration path from class components before committing to the implementation in React 16.8.
• Internal platform deprecation: A platform engineering team writes RFC-0031 proposing the deprecation of their in-house job scheduling system in favor of a managed cloud offering, giving downstream teams a 12-month migration window with a documented adoption strategy.
• Developer experience standard: An engineering effectiveness team writes RFC-0015 proposing a mandatory linting standard across all repositories, documenting the motivation (inconsistent code style slowing reviews), the specific rule set, and the rollout timeline.

Related templates

• Architecture Decision Record (ADR) — after an RFC is accepted, the final decision is often captured in an ADR for the relevant repository.
• Design Document (Tech Spec) — an accepted RFC typically triggers the creation of one or more design docs for the implementation work.
• Governance — RFC processes are a core tool in engineering governance frameworks.

Further reading

• Rust RFC Process – official documentation and accepted RFC corpus
• React RFCs – GitHub repository with historical RFCs including the Hooks proposal
• Ember RFCs – another well-documented open-source RFC process