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