Thanks for bubbling this thread back up to the top Donat. I think a “cleaner slate” v4 API has a lot going for it, but if we go that route without also supporting the v3 API at the same time we’ll be sunk. Python succeeded in spite of the 2->3 transition, but it was a long and painful road as Joan points out. I’d rather get people on the new version and have them adopt new APIs over time there, rather than make all of that work a gate on adopting 4.0.
>>>> 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? That seems like a good set of questions to work through. I wouldn’t think this requires any changes to 3.x and would be something we could introduce going forward in 4.0. As to whether we support N-1, N-2, … versions of the API, I don’t have a strong opinion at the moment. 5.0 is a long ways off :) Cheers, Adam > On Mar 30, 2021, at 4:27 PM, Joan Touzet <woh...@apache.org> wrote: > > > > On 2021-03-30 2:35 p.m., Bessenyei Balázs Donát wrote: >>> It'd be like a Python 2 -> 3 transition >> >> I think the simile is spot on. >> But that shouldn't be a problem, it's more like evolution. >> >>> your user base plummet >> >> Looking at [1] and for lack of a better idea for reference [2], the >> user base issues are not obvious to me. > > It also took them 12 years to get back to that point. Python 3.0 came > out in December 2008. It took until Python 3.5-3.6 or so (3.6 was > released in 2016) before people really started taking Python 3 seriously > for production at scale, I believe. The rest of the people were forced > off of it with the end of support for 2.7 at the beginning of last year. > > If he's back from break, Paul Davis can tell you about all the horrors > of the transition. It was not pretty. > >> Having said that, I'm okay with dropping the idea, I just want to make >> sure it's also considered. > > Not railing against it, just saying, if you expect to succeed, you will > need to do a *LOT* more community work than throwing a release over the > wall and calling it done. It would be wise to at least look into why > Python had such a hard time, and start making concrete plans (and > dedication of people) to avoid a similar trajectory. > > -Joan > >> >> [1]: https://www.jetbrains.com/lp/python-developers-survey-2020/ >> [2]: https://www.tiobe.com/tiobe-index// >> >> On Tue, Mar 30, 2021 at 7:20 PM Joan Touzet <woh...@apache.org> wrote: >>> >>> >>> >>> 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
