The intent of the RFCs was to give people a place to look at what's
being done, comment on the implementation decisions, and to form the
basis for eventual documentation.
I think they've been relatively successful on the first two pieces, but
it sounds like they've fallen behind, especially because we have quite a
few languishing PRs over in the couchdb-documentation repo.
My hope had been that those PRs would land much faster - even if they
were WIPs - and would get updated regularly with new PRs.
Is that too onerous of a request?
I agree with Adam that the level of detail doesn't have to be there in
great detail when it comes to implementation decisions. It only really
needs to be there in detail for API changes, so we have good source
material for the eventual documentation side of things. Since 4.0 is
meant to be largely API compatible with 3.0, I hope this is also in-line
with expectations.
-Joan "engineering, more than anything, means writing it down" Touzet
On 2020-05-13 8:53 a.m., Adam Kocoloski wrote:
I do find them useful and would be glad to see us maintain some sort of “system
architecture guide” as a living document. I understand that can be a challenge
when things are evolving quickly, though I also think that if there’s a
substantial change to the design from the RFC it could be worth a note to dev@
to call that out.
I imagine we can omit some level of detail from these documents to still
capture the main points of the data model and data flows without needing to
update them e.g. every time a new field is added to a packed value.
Cheers, Adam
On May 13, 2020, at 5:29 AM, Garren Smith <[email protected]> wrote:
Hi All,
The majority of RFC's for CouchDB 4.x have gone stale and I want to know
what everyone thinks we should do about it? Do you find the RFC's useful?
So far I've found maintaining the RFC's really difficult. Often we write an
RFC, then write the code. The code often ends up quite different from how
we thought it would when writing the RFC. Following that smaller code
changes and improvements to a section moves the codebase even further from
the RFC design. Do we keep updating the RFC for every change or should we
leave it at a certain point?
I've found the discussion emails to be really useful way to explore the
high-level design of each new feature. I would probably prefer that we
continue the discussion emails but don't do the RFC unless its a feature
that a lot of people want to be involved in the design.
Cheers
Garren
