Hi everyone,
One thing that has plagued the CouchDB project for a while is the
introduction of new features without much discussion prior to the
feature landing.
To put all the cards on the table: it is good that IBM/Cloudant have
been benevolent and have contributed significant new functionality with
every recent release of CouchDB. Some highlights include:
2.0: clustering code (née bigcouch)
2.1: replication scheduler
2.2: pluggable storage engines
2.3: clustered purge
However, most of these features landed as PRs on the CouchDB repository
already complete, or at the very least, with the design process already
finished, with only implementation details remaining. In at least a
couple of the cases, the PRs were so large that any review by
non-Cloudant people was effectively impossible. And, of course, by the
time the PR lands, any prototype implementations that would have
informed the final PR (and helped understand how it works) are not
visible or available. Further, documentation is often lacking at this
stage, though increasingly I see excellent README.md files placed at the
top of each OTP application that are especially welcome.
This needs to change.
Fortunately, the Internet has a good precedent for dealing with this
very issue: the RFC[1]. While we don't need the entire pomp and
circumstance workflow that follows the RFC, we can certainly steal that
nice template.
I've taken a pass at adapting the RFC template to GitHub's and
CouchDB's needs (PRs welcome):
https://raw.githubusercontent.com/apache/couchdb/master/.github/ISSUE_TEMPLATE/rfc.md
https://github.com/apache/couchdb/issues/new?labels=rfc%2C+discussion&template=rfc.md
I believe this template is not onerous to fill out, and if it contained
sufficient detail on the proposal, would give committers enough knowledge
to be able to make informed decisions about the proposal - i.e., vote on
it.
I propose the PMC REQUIRE this template for any substantial change to
CouchDB's HTTP API, or its behaviour.
I propose developers SHOULD use this template for any change to
CouchDB's HTTP API or behaviour, even small ones.
I propose developers COULD use this template for any minor change to
CouchDB, but it's unnecessary if it's something like a debug interface,
a config file improvement, etc. Documentation and Fauxton changes would
likely be exempt from this workflow, too.
I imagine the workflow being like this:
* [DISCUSS]ions like the ones happening now for FDB happen on the list.
* Consensus starts to be reached, or, at the very least, the important
advantages and disadvantages of the proposal have been clarified.
* A filled-in RFC is filed in GH Issues.
* (Optional.) A bot watches for issues of this type and forwards notice
of them to dev@. This becomes a [PROPOSAL] per our bylaws at that
point.
* Committers formally vote +1/+0.5/0/-0.5/-1 on the proposal in GH.
* (Optional.) A bot could close the vote and sum the responses from
committers, emailing the results to dev@.
* Repeat if necessary (because the RFC gets rewritten/improved, etc.)
Note the only two new steps are 1) ensuring that we actually HAVE the
discussion on the mailing list about the proposed change; and 2) a new
template we should use for these major changes, which itself should help
make understanding the proposal and the voting process smoother.
For me, the question that remains is: at what point do we REQUIRE the
proposed RFC process to be followed? When is a change "substantial?" And
I think that it may be sufficient at this point to leave it grey-area,
with the PMC weighing in as a group if necessary. (The easiest thing to
do is to simply say "do the RFC anyway," because if any proposal is
sufficiently unclear as to not be easily translatable into an RFC, then
it is probably too weak of a proposal to stand muster without one.)
One other question is whether or not we add a new decision type to our
decision matrix in the Bylaws for this. Our rules are somewhat unclear
here, since this is both a technical and a non-technical decision,
meaning it probably defaults over to our non-technical decision type.
That type is lazy majority, with committers being given binding votes,
but importantly does NOT allow for vetoes (blocking -1 votes). (I have
one other topic for the Bylaws mailing, which will be separate, so we
can pick up this discusison in that thread if desired.)
Thoughts?
-Joan "evolve or perish!" Touzet
[1]: https://www.ietf.org/standards/rfcs/
