The result of an RFC is often a decision. One that results in an implementation, or a decision not to implement for some reason. Some times we mark the RFC as solved, and some times that includes some description or link to the solution. This is not always the case and there many instances where a review of an RFC does not indicate the end result.
Proposal
I am proposing we introduce a template for RFCs that include a decision section. This would bridge the gap between RFCs and the Architecture Decision Record ideas. This would give some structure for writing RFCs to help in writing them, and indicate a clear place to denote the outcome.
Template Proposal:
# RFC: <Full title of the RFC>
[Optional] Decision Due Date: <target date to make a decision>
## Context and Problem Statement
* What is the problem being solved?
* How does this affect the user or developer?
* Background information that helps understand the current state.
* Include any technical objectives
* Include any non-goals
## Proposal
* Include all relevant details of the solution
* Include any technical and project level impacts
### Alternative Designs
* Include any alternative solutions, and why they are not preferred
## Decision Outcome
What was the decision that was ultimately made and relevant outcomes with links.
## Impacts
Record impacts that the decision has such as limitations, changes to the architecture, affects to workflows, processes or user facing consequences.
Decision
This template has been implemented and will now appear whenever a new RFC is created.
I would be even more descriptive and put more examples for each section, which might be in the form of questions or checklists that each section should answer.
What’s the difference between RFC and Architecture Decision Record?
I think RFC tends to be un-structured and entirely flexible, and can have a provision for decisions if the community defines it. The Architecture Decision Record tries to be prescriptive of having a structure for the document, getting comments, approval and then storing the record of the decision made.
I made updates to the template. Let me know what else you’d like to see.
Template sounds as a great idea. Could it also include “time the decision is needed by” point? It may be optional, but in many cases, it would be useful to set the expectations for reactions.
While at it, should we create a separate RFC category? Sometimes we see RFCs in Development sometimes in Community, sometimes they are prefix with RFC, sometimes they are tagged. It it becomes it’s own category, the template can be prepopulated for every new post.
