To be Reviewed By: June 25th 2019
Authors: amurmann@apache.org
Status: Draft | Discussion | Development | Active | Dropped | Superseded
Superseded by: N/A
Related: N/A
With some of our recent efforts, we have seen consensus on design decisions take a very long time. In order to be able to keep moving forward as a successful project, we need to be able to get to consensus faster and ultimately get to execution faster. Therefore I propose a slightly more formal process for us to get to consensus.
We already have gotten pretty good at sharing proposals with each other. Not much should need to change with that. It’s mainly the process around it that needs to be ironed out. This document will refer to that process as the “Request For Comments (RFC) process”. The main questions that the process needs to address are: What is enough consensus? How can we get to consensus in a reasonable time frame?
The proposed solution to address the problem described above is to have an individual author or even better a group of authors submit a proposal to the community in order to gather feedback and achieve consensus. The RFC follows the same format as used by this proposal.
Much inspiration for this proposal and in some cases whole segments have been drawn from Phil Calçado’s Structured RFC Process. This proposal adopts Calçado’s work for use in an open source project like ours.
Some aspects are also based on Apache Kafka’s KPI process.
All RFCs are created as a new wiki page under Project Proposals and Specifications. In addition a [DISCUSS] email should be send to the dev mailing list. Discussion will take place in the email thread.
Comments and feedback should be provided on the email thread and focus on the technical content. As long as they don't impact the content, collaborators should avoid commenting on formatting, writing style and other maybe relevant, but not critical aspects.
Authors must address all comments written by the deadline. This doesn't mean every comment and suggestion must be accepted and incorporated, but they must be carefully read and responded to. Comments written after the deadline may be addressed by the author, but they should be considered as a lower priority.
Every RFC has a lifecycle. The life cycle has the following phases:
When a proposal transitions to Dropped or Superseded state it should be moved under the Icebox grouping.
The proposal should be posted with a date by which the author would like to see the approval decision to be made. How much time is given to comment depends on the size and complexity of the proposed changes. Anything between 1 week and 3 weeks seems like a reasonable timespan. Driving the actual decisions should follow the lazy majority approach. If a discussion is still going strong once it’s approaching the initially set date, the author(s) might consider extending the time for discussion. This should happen explicitly and be announced in the email that starts the [DISCUSS] thread.
Writing an RFC should be entirely voluntary. There is always the option of going straight to a pull request. However, for larger changes, it might be wise to de-risk the risk of rejection of the pull request by first gathering input from the community. Therefore it’s up to every member of our community to decide themselves when they want to reach for this tool.
It’s encouraged to write an RFC for any major change. A major change might be:
Once approved the existing body of the RFC should remain immutable.
Once the proposed work starts, we likely will learn things that require minor changes to the RFC to keep it current. These changes should be captured in an Errata section at the end of the document rather than modifying the existing body of the document directly. This is to highlight that and how the approach has changed, since initial discussion.
Some things can be helpful to keep in mind when writing technical documents:
There are some existing solutions that might accomplish the same as this proposal. However, we believe that those solutions are inferior for the reasons below.
Although any collaborative development process will have feedback as a core component, the name RFC was made popular by the process used by the IETF to document fundamental standards for what eventually became the Internet. We could follow the IETF RFC model, and maybe even require authors to use terms like MUST, SHOULD, and MAY as formally specified by RFC2119 to avoid ambiguity.
The main reason to avoid this style is that IETF RFCs have evolved into "the Internet documents of record", containing "very detailed technical information" about standards that browser vendors and network middleware need to implement. These documents will impact the whole industry and hence warrant a complex publishing workflow. The process we propose in this document, on the other hand, is about putting forward an idea as early as possible and receiving feedback on it by a wide audience. With this goal in mind, a less formal process like the one described here is preferred.
Michael Nygard published a model to document and manage change in software architecture called Architecture Decision Record (ADR). The ADR seems to be more focused on documenting architectural decisions rather than on arriving at a consensus about them.
The primary problem this lightweight RFC proposal is solving is how to arrive at a consensus, not how we document architecture.
