# RFC — Template

Use for proposals that need a written decision record. Status field goes at
the top so the page reader sees it before the rest.

## Sections

- Status (DRAFT / REVIEW / ACCEPTED / REJECTED / SUPERSEDED)
- Author + reviewers (the people whose names should be on the proposal)
- Context (the problem and why now)
- Proposal (the change, in concrete terms)
- Alternatives considered (one paragraph each, with the reason rejected)
- Risks and mitigations (table)
- Rollout plan (phases, owners, rollback)
- Open questions (the things still being decided)

## Anti-patterns

- Don't write an RFC without alternatives. A proposal that has no rejected
  alternatives either didn't think hard enough or didn't consider the reader.
- Don't hide the status. The reader's first question is "is this decided?";
  answer it in the first line.
- Don't open questions at the end of the proposal. Put them after the rollout
  plan, where they don't read as part of the decision.

## Storage template

```xml
<h1>{Title — verb-first}</h1>

<ac:structured-macro ac:name="status">
  <ac:parameter ac:name="colour">Yellow</ac:parameter>
  <ac:parameter ac:name="title">DRAFT</ac:parameter>
</ac:structured-macro>

<table>
  <tbody>
    <tr>
      <th>Author</th>
      <td>{name}</td>
    </tr>
    <tr>
      <th>Reviewers</th>
      <td>{names}</td>
    </tr>
    <tr>
      <th>Status</th>
      <td>DRAFT</td>
    </tr>
  </tbody>
</table>

<h2>Context</h2>
<p>{problem + why now}</p>

<h2>Proposal</h2>
<p>{the change in concrete terms}</p>

<h2>Alternatives considered</h2>
<h3>{Alternative 1}</h3>
<p>{why rejected}</p>
<h3>{Alternative 2}</h3>
<p>{why rejected}</p>

<h2>Risks and mitigations</h2>
<table>
  <tbody>
    <tr>
      <th>Risk</th>
      <th>Mitigation</th>
    </tr>
    <tr>
      <td>{risk}</td>
      <td>{mitigation}</td>
    </tr>
  </tbody>
</table>

<h2>Rollout plan</h2>
<table>
  <tbody>
    <tr>
      <th>Phase</th>
      <th>Owner</th>
      <th>Rollback</th>
    </tr>
    <tr>
      <td>{phase}</td>
      <td>{owner}</td>
      <td>{how to roll back}</td>
    </tr>
  </tbody>
</table>

<h2>Open questions</h2>
<ul>
  <li>{question}</li>
</ul>
```

## Cross-references

- Storage macros: `confluence-page/references/macros.md`
- Status colors: `Yellow` (DRAFT), `Blue` (REVIEW), `Green` (ACCEPTED),
  `Red` (REJECTED), `Grey` (SUPERSEDED)