From 9975caf08551bbb4324e35cd41e350ae4248cd8b Mon Sep 17 00:00:00 2001 From: TonyTonyCoder11 Date: Fri, 31 Jul 2026 17:16:27 +0200 Subject: [PATCH] Say which two things 2.0.0 breaks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The release notes claimed the JVM public API was unchanged from 1.2.0, byte for byte. It is not, and the mistake is a specific one worth naming: the multiplatform migration changed no API, I measured that, and then I wrote it up as if it were true of the whole release. Between v1.2.0 and v2.0.0 the dump gains 666 lines and loses 8. The additions are cluster support, formula and MMR reranking, shard-scope snapshots and the Koog module, all merged after the 1.2.0 tag. The eight removals are the old constructor and copy signatures of ScrollRequest and SearchRequest, which gained a shardKey parameter. Source still compiles, because the parameter is defaulted, but copy() called against a 1.x jar does not — which is exactly the case STABILITY.md already described in the abstract, arriving for real. So the major is justified twice over rather than once, and the honest version is more useful than the one it replaces: a reader who calls copy() on either type now learns they have to recompile, where before they were told nothing had changed. The narrow claim survives and is worth keeping, because it is the part that sounds like it should have broken something: the multiplatform migration's own diff on the api dump is empty. --- CHANGELOG.md | 15 ++++++++------- README.md | 4 ++-- STABILITY.md | 32 ++++++++++++++++++++------------ 3 files changed, 30 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a38962e..eb9d1f2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,11 +12,12 @@ Tier 5, complete, and the release the transport seam was built for. `kdrant-tran opt-in gRPC engine behind the same `QdrantClient`, and `kdrant-core` compiles for the JVM and eight Kotlin/Native targets. Adding a second engine changed no line of `kdrant-core`. -**The major bump is for the artifact layout, not the API.** The JVM public API is unchanged byte for -byte — `apiCheck` reports no diff against `1.2.0`. `kdrant-core`'s JVM classes moved to -`kdrant-core-jvm` because the module is multiplatform now: a Gradle build changes only the version -number, a Maven build naming `kdrant-core` has to move. See -[STABILITY.md](STABILITY.md#upgrading-from-1-x). +**Two things make this a major.** `kdrant-core`'s JVM classes moved to `kdrant-core-jvm`, because the +module is multiplatform now: a Gradle build changes only the version number, a Maven build naming +`kdrant-core` has to move. And `ScrollRequest` and `SearchRequest` gained a `shardKey` parameter, which +changed their generated constructor and `copy`, so code that called `copy()` on either against a `1.x` +jar has to be recompiled. Source stays compatible. The multiplatform migration itself changed no public +API at all. See [STABILITY.md](STABILITY.md#upgrading-from-1-x). ### Added @@ -85,8 +86,8 @@ number, a Maven build naming `kdrant-core` has to move. See - **`kdrant-core`'s artifact layout changed with the multiplatform move.** The `kdrant-core` coordinate now carries Gradle module metadata and the JVM classes live in `kdrant-core-jvm`. A Gradle build resolves the right variant from the same coordinate and needs no change; a Maven build names the - artifact directly and must move to `kdrant-core-jvm`, which the BOM now constrains as well. The JVM - public API is unchanged, byte for byte — `apiCheck` reports no diff. + artifact directly and must move to `kdrant-core-jvm`, which the BOM now constrains as well. The + migration changed no public API: the `*.api` dump is identical either side of it. - The default dispatcher is platform-dependent, and is the one declaration the migration had to split. It stays `Dispatchers.IO` on the JVM. On Kotlin/Native it is `Dispatchers.Default`, because the coroutines library still keeps its native IO dispatcher internal. Passing your own dispatcher works diff --git a/README.md b/README.md index f24e24e..d9d7a57 100644 --- a/README.md +++ b/README.md @@ -354,8 +354,8 @@ the target would ship a DSL with nothing to send. `kdrant-transport-grpc` is an opt-in gRPC engine behind the same `QdrantClient`, generated from Qdrant's own `.proto` files rather than wrapping the official client, so a REST build still resolves no gRPC, no protobuf and no Netty — checked on every build, not asserted. And `kdrant-core` moved to Kotlin -Multiplatform: the JVM plus eight Kotlin/Native targets, with the JVM public API unchanged byte for -byte. Both engines are now held to one shared behavioural suite against a real Qdrant. The major bump is +Multiplatform: the JVM plus eight Kotlin/Native targets, a migration that changed no public API at +all. Both engines are now held to one shared behavioural suite against a real Qdrant. The major bump is for the artifact layout, not the API: `kdrant-core`'s JVM classes moved to `kdrant-core-jvm`, which a Gradle build does not notice and a Maven build does. See [STABILITY.md](STABILITY.md#upgrading-from-1-x). diff --git a/STABILITY.md b/STABILITY.md index 43c9cab..bcec11e 100644 --- a/STABILITY.md +++ b/STABILITY.md @@ -68,20 +68,28 @@ Within a major version: ## Upgrading from `1.x` -`2.0.0` breaks one thing, and it is not the API. **The JVM public API is unchanged, byte for byte** — -`apiCheck` reports no diff against `1.2.0`. What changed is where `kdrant-core`'s JVM classes are -published. - -`kdrant-core` is now a Kotlin Multiplatform library, so its own coordinate carries Gradle module -metadata and the JVM classes live in `kdrant-core-jvm`. Gradle reads that metadata and resolves the -variant, so **a Gradle build changes nothing but the version number**. Maven does not read it, so a -Maven build naming `kdrant-core` gets no classes and must move to `kdrant-core-jvm`. Depending on -`kdrant-transport-rest` or `kdrant-transport-grpc`, which is what the README recommends, is unaffected -either way. - -The rest of `2.0.0` is additive: the gRPC engine is a module you do not have, and every `1.x` call site +`2.0.0` breaks two things, and **source compatibility is not one of them**: every `1.x` call site compiles unchanged. +**Where `kdrant-core`'s JVM classes are published.** The module is Kotlin Multiplatform now, so its own +coordinate carries Gradle module metadata and the classes live in `kdrant-core-jvm`. Gradle reads that +metadata and resolves the variant, so a Gradle build changes nothing but the version number. Maven does +not read it, so a Maven build naming `kdrant-core` gets no classes and must move to `kdrant-core-jvm`. +Depending on `kdrant-transport-rest` or `kdrant-transport-grpc`, which is what the README recommends, is +unaffected either way. + +**`ScrollRequest` and `SearchRequest` gained a `shardKey` parameter.** That is the case +[above](#what-may-still-change-in-a-minor) arriving for real: the constructor keeps its defaults and +source keeps compiling, but the generated `copy` and `componentN` changed, so code that called `copy()` +on either type against a `1.x` jar has to be recompiled. Nothing else in the `*.api` dump was removed. + +**The multiplatform migration itself changed no public API.** The dump is identical either side of it, +which is worth stating because it is the part that sounds like it should have broken something. What +broke is the two lines above. + +The rest of `2.0.0` is additive: the gRPC engine is a module you do not have yet, and cluster support, +formula and MMR reranking, shard-scope snapshots and the Koog module are new operations. + ## Java interoperability Kdrant is deliberately **Kotlin-coroutine-first** — that is the wedge (see the [README](README.md)). The