couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jan Lehnardt <>
Subject Releasing experimental features (was: Re: [PROPOSAL] Port _db_updates from rcouch to master)
Date Mon, 22 Jul 2013 09:48:51 GMT

On Jul 21, 2013, at 10:48 , Noah Slater <> wrote:

> Woop! Great to see a merge request. Good to be moving ahead with our new
> workflows.
> I'm torn on the testing issue. One the one hand, I think we should stick to
> our guns, and only merge in features with proper tests and docs, and so on.
> (The monthly release cycle should remove any sense of urgency here.)
> On the other hand, Jan's proposal seems reasonable. I only worry that if we
> merge the feature now, it may mean that we are waiting longer for the
> tests. (As the pressure to write them goes away.)
> Also, this brings up the interesting question of what we do about
> experimental or new features that we want people to test. Do we advertise
> dev builds from feature branches, or do we merge into master and mark as
> experimental? (And does the experimental status of a feature relate to how
> many tests we require at merge time?)
> Good questions to address and document for future merge proposals!
> I'm not gonna state an opinion either way. I'm sure you folks can figure
> out the best way forward here. :)

Thanks Noah, these are great points we should talk about.

Here’s my thinking. I learned about the notion of EXPERIMENTAL releases
from the PHP community way back when. The skeleton you would build a
new extension from would set the state of the extension to EXPERIMENTAL
by default and it would be custom to remove that, once the author(s) and
the community deemed it ready for production. I don’t recall if there
was ever a formal process for that, but that doesn’t matter here.

The idea of course is avoiding the chicken & egg problem of trying to
ship stable software and only getting bug reports when code is released.
The trick is easy: release the code and mark it, so that at least
*some* people get to run it through its paces and report back errors
that can be fixed to go closer to removing EXPERIMENTAL stage, but not
everybody expects it to run flawlessly.

Then I completely forgot about this in the context of CouchDB. Because
we take stability so seriously, it didn’t occur to me that we could
release EXPERIMENTAL code. This came to a standoff during the CORS
development. We didn’t feel comfortable shipping it, but we didn’t
have any way to get more testing done without shipping this code.

I don’t remember who had the idea, but we ended up shipping CORS as
EXPERIMENTAL and it was exactly the right thing to do and I think this
could be a model for future features.

* * *

The Node.js folks have an interesting addition to this: Instead of
a binary EXPERIMENTAL vs. STABLE bit, they have a 6 point scale from

0. Deprecated
2. Unstable
3. Stable
4. Frozen
5. Locked

See for the individual

I wouldn’t mind adopting this for our API to communicate the state of
certain features and API calls.

We have talked about deprecating features using HTTP headers like
`X-Couch-Deprecated: true` to denote a deprecation to be included in
releases that happen before the actual removal of a feature. We could
make that `X-Couch-API-Stability: [0-5]` instead, if we adopt the scale
above (and maybe only optionally show anything >0 to save some bytes
in the general case). And whatever powers that information could be
used to feed into the capabilities we have talked about for the welcome
message on `/`.

I hope this makes sense :)

What do you think?


> On 20 July 2013 20:38, Benoit Chesneau <> wrote:
>> +1.
>> On Wed, Jul 17, 2013 at 10:00 PM, Jan Lehnardt <> wrote:
>>> Hi all,
>>> I would like to propose (lazy consensus) to port the _db_updates
>>> feature from rcouch to master before the next release.
>>> The code exists in a branch on ASF git (1684-feature-db-updates).
>>> Copying the full commit status:
>>> Import _db_updates from rcouch.
>>> This creates a new top level API endpoint: `/_db_updates`
>>> that returns a line of JSON for each database event along
>>> with the database name.
>>> A database event is one of `created`, `updated`, `deleted`.
>>> The API endpoint supports a `?feed=` parameter with the
>>> options: `longpoll`, `continuous` and `eventsource`.
>>> A second parameter `timeout=` specifies when the server should
>>> close the connection.
>>> `longpoll` closes the connection after a single notification.
>>> It is the default option.
>>> `continuous` keeps a socket open until the specified `timeout`
>>> or 60 seconds by default.
>>> `eventsource` works like continuous, but sends the data in
>>> EventSource format. See
>>> The parameters are modelled after the existing `/_changes` API
>>> endpoint. Note that `/_db_updates` does not support resuming
>>> of notifications via a sequence ID.
>>> This is a port of the existing DbUpdateNotification interface
>>> to the HTTP API.
>>> Functional changes compared to rcouch:
>>> - make _db_updates an admin-only resource
>>> Docs:
>>> - updated api/misc to include basic info on `/_db_updates`
>>> License:
>>>  Apache 2 license, updated LICENSE.
>>> Notice:
>>>  (c) 2012 Benoit Chesneau, updated NOTICE.
>>> Tests:
>>> - only manual testing of the various API differences due to
>>>   complications with asynchronous HTTP requests in the JS
>>>   test suite and total annoyance of overly complicated
>>>   ibrowse/httpc modules for writing etap tests.
>>> Recommendation to ship this as EXPERIMENTAL until we have tests.
>>> Cheers
>>> Jan
>>> --
> -- 
> NS

View raw message