I think that's a good compromise if we want to bring more users along from 3.x to 4.x.
In respect to existing users I can see there being at least 4 different categories: 1. Users who know about the snapshotting behavior of 1.x-3.x, and their applications rely on it for correctness. 2. Users who don't know about the snapshotting, and their applications rely on it for correctness. 3. Users who know about the snapshotting behavior, but their applications don't rely on it for correctness. 4. Users who don't know about the snapshotting behavior and their applications don't rely on it for correctness I worry about 1 and especially 2. Documenting the differences in behavior there would be crucial. Hopefully after learning about the feature a bit more, the majority of those users will be able to tell if it affects their application or not. At the same time, the users in category 3 and 4 won't feel like they need to do a lot of grunt work for seemingly no reason, if they want to use 4.x for scalability or other reasons like not having to deal with spurious conflicts. Good point that being explicit about versions would allow us to not worry as much about in-place backward compatibility. I like the idea of the v4 API getting all kinds of new and interesting features: transactional PATCH across multiple docs, bulk docs with transactional guarantees and so on -- it would offer enough of a "carrot" for users to look forward to and want to use the new API, instead of being forced by the "stick" of the old API being removed. As for the warnings and global vs per endpoint, I think global and no warnings might be a good start? We can always add warnings and per-endpoint schemas later, but it's harder to remove them once we've already added them. -Nick On Mon, Feb 22, 2021 at 8:48 PM Adam Kocoloski <kocol...@apache.org> 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
