Skip to content

README.md

Latest commit

 

History

History
163 lines (114 loc) · 3.87 KB

README.md

File metadata and controls

163 lines (114 loc) · 3.87 KB

RFCs

Proposals that need buy-in before proceeding.

What Belongs Here

RFCs are for proposals that require alignment from others:

  • Changes to public API surface
  • Product direction decisions
  • User-facing developer experience changes
  • Significant changes to core architecture

When to Write an RFC

Write an RFC when:

  • Changes public API surface
  • Affects product direction
  • Affects user-facing developer experience
  • Significant changes to core architecture
  • Needs buy-in from others

Use a Design Doc instead (internal/design/) for decisions you own — architectural choices in your area, internal patterns, component specs.

Skip both for: Bug fixes, small features, implementation details, documentation updates.

File Format

RFCs use a YAML frontmatter header for status tracking:

---
status: draft
---

# Title

## Problem Statement

What are we trying to solve?
What user or system behavior is driving this question?
What happens if we do nothing?

## Customer Salience

Before proposing solutions, assess how much this actually matters to customers.

**Who is affected?**
- Viewers of the player?
- Player integrators?
- Open source contributors?
- Skin creators / player engineers?
- New users?

**How many customers are realistically impacted?**
- Nearly everyone?
- A meaningful minority?
- A small edge case group?

**How strongly would they feel about it?**
- Would they notice?
- Would it mildly annoy them?
- Would it meaningfully degrade their experience?
- Would it prevent them from using the product?

Are we reacting to a hypothetical user or to current observable behavior?

## Options Considered

For each option:

**Option N: Name**

Describe the approach clearly and concretely.

- What does this enable?
- What does it constrain?
- Does it meaningfully increase complexity?
- Does it create tight coupling or future rigidity?
- Is it reversible? If we are wrong, how painful is it to change course?

Be honest about tradeoffs. Avoid overstating benefits or minimizing costs.

## Recommendation

Choose one option. Explain why it is the right tradeoff given:

- The actual level of customer salience
- Product direction
- Technical consequences
- Urgency

If customer impact is low, explain why we should avoid over-optimizing. If it is high, explain why the investment is justified.

## Final Decision

*(Completed after review)*

**Decision:**
**Rationale:**
**Date:**

When implemented, add implementation details:

---
status: implemented
implemented-in: v10.0.0-alpha.5
implementation-plan: .claude/plans/example.md
---

Status Lifecycle

Status Meaning
draft Under discussion, not yet accepted
accepted Approved for implementation
implemented Code shipped
superseded Replaced by another RFC

Directory Structure

rfc/
├── README.md           # This file
├── feature-name.md     # Single-file RFC
└── feature-name/       # Multi-file RFC
    ├── index.md        # Overview and quick start
    ├── decisions.md    # Design decisions and rationale
    └── examples.md     # Usage examples

Contributing an RFC

Branch and PR Workflow

  1. Create branch: rfc/feature-name
  2. PR title while open: [RFC] Feature Name
  3. Squash commit when merged: docs(rfc): feature name

Example

git checkout -b rfc/player-api
# ... write RFC ...
git push -u origin rfc/player-api
gh pr create --title "[RFC] Player API"

When the RFC is accepted and merged, the squash commit becomes:

docs(rfc): player api

See Also