Running an RFC
A Request for Comments (RFC) is where a change gets proposed and debated before anyone commits to it. Colleagues comment on the proposal while it is open, the comment period runs on a fixed clock, and when it closes you can turn the outcome into a draft decision record in one click.
RFCs are available on every plan. You need the Member role or higher to create an RFC or comment on one. See Members and roles.
The RFC lifecycle
Every RFC moves through three states:
- Draft: your working copy. Only the authors (and admins) can edit it.
- Open: the proposal is locked and open for comments. This is the only state that accepts comments.
- Closed: the comment period is over. Comments are locked and you decide what happens next.
1. Create a draft
- Open RFCs in the sidebar and choose + New RFC.
- Enter a Title.
- Add any co-authors under Authors. Co-authors can edit the draft and manage the RFC just like you.
- Write the proposal in Body (Markdown). The body starts from your
workspace's RFC template, which by default has these sections:
- Summary: one paragraph on what is proposed and why it matters.
- Motivation: the problem, who is affected, and the cost of doing nothing.
- Proposal: the detailed design, with diagrams and examples.
- Alternatives: other approaches and why this one is preferred.
- Drawbacks & risks: costs, trade-offs, and risks.
- Open questions: points to settle while the RFC is open.
- Choose Create draft.
While the RFC is a draft you can return to it and choose Edit, then Save draft, as often as you like. Admins can change the starting template in Artifact types and templates.
2. Open it for comments
When the proposal is ready, choose Open RFC for Comments. The RFC moves to Open and its body is locked so everyone comments on the same text.
The comment period runs for 60 days. The RFC page shows how long is left, for example Closes in 12d, and flags the RFC as overdue if the deadline has passed.
3. Discuss in the comments
While the RFC is Open, anyone with the Member role or higher can open the Comments tab, write a comment, and choose Comment.
- You can edit or delete your own comment for 10 minutes after posting it. After that it is fixed.
- A deleted comment is shown as comment deleted so the thread still makes sense.
- Viewers can read the discussion but not comment.
- Comments are not accepted while the RFC is a draft, and they lock when the RFC closes.
4. Extend or close the comment period
Reminder. On day 55 of the comment period, every author gets an in-app notification and an email saying the RFC closes for comments soon. See Notifications.
Extend. From day 55 onward, authors (and admins) see Extend to 90 days. This moves the deadline to 90 days after the RFC was opened. You can extend an RFC once; the page then shows (extended) next to the deadline.
Close. Authors (and admins) can choose Close at any time while the RFC is open. If nobody closes it, the RFC closes automatically once the deadline passes.
5. Act on the outcome
When an RFC is Closed, authors (and admins) get two options:
- Build Decision creates a new draft decision record (ADR) with the same title and the RFC's content, and takes you to it. The ADR is linked back to the RFC, so the discussion behind the decision is never lost. From there the ADR follows the normal review and approval flow.
- Revise creates a new draft RFC with the same title, body, and co-authors, and takes you to it. The new RFC is recorded as superseding the original, so the first round stays on record. Use this when the debate showed the proposal needs another pass.
You can do either, or both, from the same closed RFC.
Who can do what
| Action | Who |
|---|---|
| Create an RFC | Member and above |
| Edit a draft, open for comments, extend, close | The RFC's authors, or an admin |
| Comment | Member and above, while Open |
| Build Decision, Revise | The RFC's authors, or an admin |