Internal RFC Template

Technical decisions must be traceable and refutable.

This is the format we use for RFCs (Request for Comments) in our team. Every cross-team technical decision, every new system going live, every third-party dependency we bring in, must go through an RFC.

Metadata (YAML header)

---
id: 0042            # monotonically increasing
title: Replacing ClickHouse with Doris on the BI side
status: proposed    # proposed | accepted | rejected | superseded
authors: [tommy, alex]
date: 2026-07-22
deciders: [data-platform, infra]
---

Body structure

1. Context (why this RFC exists)

2–3 paragraphs explaining what triggered this. Possibly: an upstream system changed, performance broke, a library stopped being maintained, a new business requirement.

Write the trigger, not the history.

2. Proposal (one sentence)

One sentence describing what we want to do. Readers should know what you’re planning after reading that one sentence.

3. Detailed design (length follows complexity)

• Data-flow diagram (required)
• Interface changes (required)
• Database schema changes (if any)
• Third-party dependencies (must come with a reason)

4. Alternatives considered (what we thought through)

List every path + why we didn’t pick it. Including “do nothing”.

5. Risks & mitigations

• Performance / availability impact
• Rollback cost
• People dependencies

6. Rollout plan

Phased. Each phase has clear acceptance criteria.

Review process

1. Author opens PR → label rfc
2. Within 48h deciders must give their verdict (accept / reject / revise)
3. Objections must leave a comment + alternative
4. Accepted ≠ unanimous. What you need is “no strong objections + at least 2 deciders in support”

RFC anti-patterns

• ❌ “We discussed this earlier…” → that’s a verbal decision, not an RFC
• ❌ Writing the RFC like a solution doc → an RFC is about the why; the solution doc is written after the RFC is accepted
• ❌ Writing 30 pages → nobody will read it. 3 pages max is a reasonable target
• ❌ No alternatives section → means the author didn’t think it through

Why we insist

The company’s main loop is signal → selection → launch → optimize. The RFC is the artifact produced during the selection stage.

Decisions without RFCs are black-box decisions—next time a new hire asks “why did we do it this way?” nobody can answer.