RFC (Request for Comments) Process¶

Goal: Collaborative decision-making on major changes

What is an RFC?¶

An RFC is a design document proposing a significant change. It invites feedback from the team before implementation begins.

Use RFCs for: - New features (significant scope) - Breaking API changes - Architecture changes - Process changes

Don't need RFC for: - Small bug fixes - Documentation updates - Minor improvements - Experimental prototypes

RFC Process¶

1. Draft RFC (Author)¶

Create RFC document following template below.

Include: - Problem statement (what are we solving?) - Proposed solution (how will we solve it?) - Alternatives considered - Risks and unknowns - Success criteria

Format: Markdown document in Google Docs, GitHub Discussion, or shared doc

Post RFC in team channel:

📋 RFC: [Title]

I've written an RFC for [brief description]. Looking for feedback on the approach.

Doc: [link]
Feedback deadline: [date, 3-5 days from now]

Key questions:
- Does this solve the problem?
- Are there better approaches?
- What am I missing?

Please comment in doc or reply here. Thanks!

Feedback period: 3-5 working days (depends on urgency and complexity)

3. Incorporate Feedback (Author)¶

Read all comments, respond to questions: - Accept: Update RFC with suggestions - Reject: Explain why (respectfully) - Discuss: Start thread if need more input

Goal: Convergence, not consensus (can't please everyone)

4. Meeting (If Needed)¶

Most RFCs don't need meeting (async discussion sufficient)

Schedule meeting if: - Complex tradeoffs - Strong disagreement - Need real-time brainstorming

Meeting agenda: 1. Present RFC (10 min) 2. Q&A (20 min) 3. Discussion (20 min) 4. Decision (10 min)

5. Decision (Author or Tech Lead)¶

Author makes final decision after considering feedback

Document decision: - Update RFC with final decision - Add "Status: Accepted" or "Status: Rejected" - Summarize key changes from feedback - Thank contributors

Create ADR if decision is architectural

6. Implementation¶

If accepted: - Create issues for implementation - Link to RFC from issues - Track progress - Update RFC if implementation differs

RFC Template¶

# RFC: [Title]

**Author**: @username
**Date**: YYYY-MM-DD
**Status**: Draft | In Review | Accepted | Rejected | Implemented
**PR**: #XXX (if applicable)

## Summary

[1-2 paragraph summary of proposal]

## Problem Statement

**What problem are we trying to solve?**
-

**Why is this important?**
-

**Who is affected?**
-

## Proposed Solution

**High-level approach**:
[Describe solution in plain language]

**Key design decisions**:
1. Decision 1 (and rationale)
2. Decision 2 (and rationale)

**Example usage** (if API change):
```cpp
// Example code showing how it would be used

Implementation sketch: [Rough implementation plan, doesn't have to be detailed]

Alternatives Considered¶

Alternative 1: [Name]¶

Approach: [Description] Pros: - Cons: - Why not chosen: -

Alternative 2: [Name]¶

[Same format]

Alternative 3: Do Nothing¶

Pros: No work required Cons: Problem persists Why not chosen: [Why status quo is unacceptable]

Risks and Unknowns¶

Technical risks:¶

Unknowns (need to investigate):¶

Mitigations:¶

Success Criteria¶

How will we know this is successful? - [ ] Criterion 1 (measurable) - [ ] Criterion 2 - [ ] Criterion 3

Timeline¶

Estimated effort: [2 weeks, 1 month, etc.]

Milestones: 1. [Phase 1] 2. [Phase 2] 3. [Phase 3]

Dependencies:¶

Open Questions¶

Question 1?
Question 2?

[Resolve these before finalizing]

References¶

[Related RFC/ADR]
[External docs]
[Research papers]

Feedback Summary¶

[After feedback period, summarize key feedback and how you addressed it]

Major feedback: - Feedback 1 → Addressed by [change] - Feedback 2 → Not addressed because [reason]

Changes made: - Change 1 - Change 2

Still open: - Question 1 (need more input) ```

Examples¶

Example: Small RFC (Async Discussion Sufficient)¶

RFC: Add dry/wet mix parameter to all effects

Process: 1. Author writes 1-page RFC 2. Posts in Slack, 3-day feedback window 3. Team comments (mostly supportive, minor suggestions) 4. Author updates RFC, marks "Accepted" 5. Creates issue, implements

Total time: 1 week

Example: Large RFC (Needs Meeting)¶

RFC: Rewrite state management with new architecture

Process: 1. Author writes 5-page RFC with diagrams 2. Posts in Slack, 5-day feedback window 3. Major questions and concerns raised 4. Author schedules 1-hour meeting 5. Meeting: Present, discuss, converge on approach 6. Author updates RFC based on meeting 7. Final review (async), marks "Accepted" 8. Creates ADR-042 documenting decision 9. Creates issues for implementation

Total time: 3 weeks (including implementation)

Tips for Good RFCs¶

Writing¶

Be clear: - Use plain language - Define acronyms - Include examples

Be concise: - 1-3 pages ideal - Use bullet points - Diagrams help

Be thorough: - Consider alternatives - Identify risks - Define success

Getting Feedback¶

Ask specific questions: - "Does this API make sense?" - "Am I missing any edge cases?" - "Is this too complex?"

Invite dissent: - "What could go wrong?" - "Why might this be a bad idea?" - "What am I not considering?"

Respond graciously: - Thank commenters - Explain decisions - Accept criticism

Making Decisions¶

Seek agreement, not unanimity: - Can't make everyone happy - Gather input, then decide - Explain reasoning

Be decisive: - Don't let RFC linger forever - Set deadline for decision - Move forward

Document dissent: - Note unresolved disagreements - Explain why proceeding anyway - Revisit later if needed

Anti-Patterns¶

❌ RFC Paralysis¶

Problem: Endless discussion, no decision Solution: Set deadline, author makes final call

❌ RFC Theater¶

Problem: Decision already made, RFC is formality Solution: Don't write RFC if mind made up

❌ RFC Overload¶

Problem: RFC for every tiny thing Solution: Reserve for significant changes only

❌ RFC Abandonment¶

Problem: Write RFC, then ignore feedback Solution: Genuinely consider feedback, engage

Resources¶

Remember: RFCs are for collaboration, not gatekeeping. Make the process as lightweight as reasonable.