If we are bumping major anyways, can we just go "clean slate" and promise replication compatibility only? 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? 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
