Proposed. Mix and match:
- Any expected behaviors dropped or changed from pre-existing API
versions are available only when API v4 is specified.
- Any existing behaviors, unchanged in couchdb 4, work the same whether
API v4 is specified, or not
- Any new endpoints created in couchdb 4 are available only when API v4
is specified (=404)
- - OR -, they respond with an error indicating that v4 is required
(422?)
- #include ways-of-indicating-v4
- start emitting deprecation warnings in v3 api requests
- e.g. response header: couchdb-warning: start_key is deprecated; use
startkey instead
- ...etc...
- drop v4 support for deprecations (422 error: use of deprecated
start_key)
- ? include errors @v3 requests for detected request parameters that are
clearly v4-targeted (422: feature newAndShiny requires that you
<indicate-v4-api>)
- ? be conservative: include v3 deprecation-related behaviors only when
request-header x-i-want-couchdb-v4: help me
- other things we want to deprecate @v3 =not support in v4, while the
window is (?) still open for that
- plus or minus bike-shedding on header names, message content, 422 vs
400 etc.
- Something else?
Anything about the proposed Replicator changes that would conflict with
this? I guess the replicator, making a request to a remote server whose
protocol support is uncertain, would need to start by making a request
guaranteed to fail on pre-4.0 server - e.g. with /_v4/ url prefix, and from
there, branch to the appropriate behavior for the remote server's
capabilities.
San
On Tue, Mar 30, 2021 at 2:25 PM Adam Kocoloski <kocol...@apache.org> wrote:
> 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
>
>
