On 30/03/2021 12:57, Bessenyei Balázs Donát wrote:
> If we are bumping major anyways, can we just go "clean slate" and
> promise replication compatibility only?
Basically: watch your user base plummet. It'd be like a Python 2 -> 3
transition, or a Perl 5 -> 6 one. It would take years of concerted
effort to recover.
This is why I'd thought pushing that off to 5.0, with 4.0 being the
transitional release, would be best. But I have no strong opinion.
> All that while we'd publish a migration guide that explains the
> differences and helps users adjust their implementations, but this way
> we'd get rid of some potential complexity.
>
> If we do want to go with API versioning, can someone help me with a
> worked example that shows how and when an endpoint gets a new `v_`,
> how that affects other endpoints, which versions of CouchDB need
> updating for such a change and when do we get to drop previous
> versions of the API?
I'd like to see this too.
> Thank you,
> Donat
>
> On Mon, Mar 29, 2021 at 6:28 PM Joan Touzet <woh...@apache.org> wrote:
>>
>> On 22/02/2021 20:48, Adam Kocoloski wrote:
>>> Hi all,
>>>
>>> Several times in recent months we’ve had discussions on this list about
>>> behavior changes in CouchDB 4.0 that boil down to tradeoffs between
>>>
>>> a) maintaining compatibility with current CouchDB APIs, and
>>> b) capitalizing on the transactional semantics of FoundationDB
>>>
>>> An example would be the support for large result sets in a view response:
>>> do we stitch together multiple transactions to support very large
>>> responses, or provide new pagination APIs and guarantee that each response
>>> is generated from a single isolated snapshot?
>>>
>>> I’d like to suggest that we “have our cake and eat it, too” by introducing
>>> versioned APIs as previously suggested by Ilya[1]. We’d have a V3 API that
>>> strives to maximize compatibility with CouchDB 3.x, and a V4 API that still
>>> looks and feels like CouchDB, but introduces breaking changes where
>>> necessary to provide well-defined transactional semantics. I think this
>>> explicit approach to API evolution could make life easier for client
>>> library maintainers, and also free us up to improve the API without needing
>>> to be quite as careful about in-place backwards compatibility.
>>>
>>> [1]:
>>> https://lists.apache.org/thread.html/rcc742c0fdca0363bb338b54526045720868597ea35ee6842aef174e0%40%3Cdev.couchdb.apache.org%3E
>>>
>>> What do you think? Cheers, Adam
>>
>> In general, +1, as long as the concerns raised by Bob are addressed.
>> Namely: if I point a CouchDB 1.x-3.x client at a future CouchDB 4.0, I
>> shouldn't be *too* surprised, and as much as possible should "just work."
>>
>> I've long believed that 4.0 would be a transitional version, and 5.0
>> would break things completely... so if 5.0 (or whatever) stops accepting
>> "v3" syntax, or "default" changes to "v4", fine by me.
>>
>> Also it'd be great if this was advertised in the feature strings shown
>> in `GET /` in some intelligent way. Maybe an array of API versions
>> supported?
>>
>> -Joan
