Docs for next version (#6008)

* Update nullability.mdx

* minor edits

* minor edits

* minor edits

* update NetworkInterceptor doc

* minor edits

* add a section about package Name

* Forgot to take that from the migration guide tweaks

* update package name

* add CHANGELOG

* better ordering

Author: martinbonnin

CHANGELOG.md

@@ -1,6 +1,51 @@
 Change Log
 ==========
 
+# Version 4.0.0-rc.1
+
+_2024-07-08_
+
+## New package name & evolution policy
+
+We changed the package name from `com.apollographql.apollo3` to `com.apollographql.apollo` for version 4. This is a safe default for the many years to come and works well with our new [evolution policy](https://www.apollographql.com/docs/kotlin/v4/essentials/evolution).
+
+If you are updating from version 3 or an alpha/beta version 4, you need to replace all `com.apollographql.apollo3` with `com.apollographql.apollo`
+
+## Apollo galaxy
+
+As part of this release, some of the non-core artifacts have been moved to separate coordinates and GitHub repositories. Moving forward, this will allow us to iterate faster on those artifacts while keeping the core ones more maintainable.
+
+Some of the existing symbols are kept as deprecated to ease the transition (like `MockServer` for an example). Others (the `-incubating` ones) have been removed, and you need to update them now.
+
+You can read more in the [migration guide](https://go.apollo.dev/ak-moved-artifacts).
+
+## All changes
+
+* [BREAKING][all] Change package name to `com.apollographql.apollo`
+* [BREAKING][all] Remove incubating compose support (#5987)
+* [BREAKING][all] Remove apollo-cli (#5986)
+* [BREAKING][all] Remove incubating normalized cache (#5985)
+* [BREAKING][all] Nullability: Move nullability directives to v0.4 (#6002)
+* [BREAKING][all] Suffix ApolloStore write/publish overloads with `Sync` to avoid them taking precedence over their suspend counterparts (#5976)
+* [NEW][cache] SqlNormalizedCacheFactory make sqldriver public to support Sqlcipher data encryption. (#5973)
+* [NEW][runtime] Add ApolloClient.Builder.retryOnErrorInterceptor (#5989)
+* [adapters] Deprecate apollo-adapters (#6012)
+* [🐘gradle-plugin] Rename the multi-module configurations (#6027)
+* [IJ Plugin] Tweak cache name display for Apollo 3, 4, and incubating (#6026)
+* [compiler] remove unused argument to scalarAdapterInitializer() (#5996)
+* [java] Use published version of the Java support libs (#5991)
+* [runtime] Deprecate apollo engine ktor and publish engine tests (#5988)
+* [mpp-utils] Cleanup mpp utils (#5980)
+* [CI] use `gradle/actions/setup-gradle` instead of `gradle-build-action` (#5981)
+* [infra] Update to develocity API (#5967)
+* [incubating cache] Add a CacheKeyApolloResolver based on ApolloResolver (incubating) (#5970)
+* [mockserver] Robustify TCP server (#5968)
+* [runtime] adding checks for json end_document in http batching interceptors (#5893)
+* [IJ plugin] Cache ApolloKotlinService into project settings (#5962)
+* [IJ plugin] Avoid a ConcurrentModificationException occurring in conjunction to the IJ Platform Gradle plugin. (#5959)
+* [websockets] Send Sec-WebSocket-Protocol (#5948)
+* [mockserver] Deprecate com.apollographql.apollo3.mockserver.MockServer (#5943)
+
 # Version 4.0.0-beta.7
 
 _2024-06-05_

README.md

@@ -6,9 +6,9 @@
 [![Slack](https://img.shields.io/static/v1?label=kotlinlang&message=apollo-kotlin&color=15a2f5&logo=slack)](https://app.slack.com/client/T09229ZC6/C01A6KM1SBZ)
 [![Discord](https://img.shields.io/discord/1022972389463687228.svg?color=7389D8&labelColor=6A7EC2&logo=discord&logoColor=ffffff&style=flat-square)](https://discord.com/invite/graphos)
 [![CI](https://img.shields.io/github/actions/workflow/status/apollographql/apollo-kotlin/push.yml?branch=main)](https://github.com/apollographql/apollo-kotlin/actions/workflows/push.yml?query=branch%3Amain)
-[![Maven Central](https://img.shields.io/maven-central/v/com.apollographql.apollo3/apollo-api)](https://repo1.maven.org/maven2/com/apollographql/apollo3/)
-[![Gradle Plugin](https://img.shields.io/gradle-plugin-portal/v/com.apollographql.apollo3)](https://plugins.gradle.org/plugin/com.apollographql.apollo3)
-[![OSS Snapshots](https://img.shields.io/nexus/s/com.apollographql.apollo3/apollo-api?server=https%3A%2F%2Fs01.oss.sonatype.org&label=oss-snapshots)](https://s01.oss.sonatype.org/content/repositories/snapshots/com/apollographql/apollo3/)
+[![Maven Central](https://img.shields.io/maven-central/v/com.apollographql.apollo/apollo-api)](https://repo1.maven.org/maven2/com/apollographql/apollo/)
+[![Gradle Plugin](https://img.shields.io/gradle-plugin-portal/v/com.apollographql.apollo)](https://plugins.gradle.org/plugin/com.apollographql.apollo)
+[![OSS Snapshots](https://img.shields.io/nexus/s/com.apollographql.apollo/apollo-api?server=https%3A%2F%2Fs01.oss.sonatype.org&label=oss-snapshots)](https://s01.oss.sonatype.org/content/repositories/snapshots/com/apollographql/apollo/)
 [![Revved up by Develocity](https://img.shields.io/badge/Revved%20up%20by-Develocity-06A0CE?logo=Gradle&labelColor=02303A)](https://ge.apollographql.com/scans)
 
 | ☑️  Apollo Clients User Survey |
@@ -88,15 +88,15 @@ Add the plugin to your `build.gradle.kts`:
 
 ```kotlin
 plugins {
-  id("com.apollographql.apollo3") version "4.0.0-rc.1"
+  id("com.apollographql.apollo") version "4.0.0-rc.1"
 }
 ```
 
 Add the runtime dependency:
 
 ```kotlin
 dependencies {
-  implementation("com.apollographql.apollo3:apollo-runtime:4.0.0-rc.1")
+  implementation("com.apollographql.apollo:apollo-runtime:4.0.0-rc.1")
 }
 ```
 
@@ -179,29 +179,29 @@ Installation instructions and more information can be found [here](https://githu
 
 ## Releases
 
-The latest version is [![Maven Central](https://img.shields.io/maven-central/v/com.apollographql.apollo3/apollo-api)](https://repo1.maven.org/maven2/com/apollographql/apollo3/)
+The latest version is [![Maven Central](https://img.shields.io/maven-central/v/com.apollographql.apollo/apollo-api)](https://repo1.maven.org/maven2/com/apollographql/apollo/)
 
 Check the [changelog](https://github.com/apollographql/apollo-kotlin/releases) for the release history.
 
-Releases are hosted on [Maven Central](https://repo1.maven.org/maven2/com/apollographql/apollo3/). The plugin is additionally hosted on the [Gradle Plugin Portal](https://plugins.gradle.org/plugin/com.apollographql.apollo3)
+Releases are hosted on [Maven Central](https://repo1.maven.org/maven2/com/apollographql/apollo/). The plugin is additionally hosted on the [Gradle Plugin Portal](https://plugins.gradle.org/plugin/com.apollographql.apollo)
 
 ```kotlin
 plugins {
-  id("com.apollographql.apollo3") version "4.0.0-rc.1"
+  id("com.apollographql.apollo") version "4.0.0-rc.1"
 }
 
 repositories {
   mavenCentral()
 }
 
 dependencies {
-  implementation("com.apollographql.apollo3:apollo-runtime:4.0.0-rc.1")
+  implementation("com.apollographql.apollo:apollo-runtime:4.0.0-rc.1")
 
   // Optional: if you want to use the normalized cache
-  implementation("com.apollographql.apollo3:apollo-normalized-cache-sqlite:4.0.0-rc.1")
+  implementation("com.apollographql.apollo:apollo-normalized-cache-sqlite:4.0.0-rc.1")
   // Optional: if you just want the generated models and parsers and write your own HTTP code/cache code, you can remove apollo-runtime
   // and use apollo-api instead
-  implementation("com.apollographql.apollo3:apollo-api:4.0.0-rc.1")
+  implementation("com.apollographql.apollo:apollo-api:4.0.0-rc.1")
 }
 ```
 

docs/source/advanced/apollo-ast.mdx

@@ -21,7 +21,7 @@ Add the `apollo-ast` dependency to your project:
 dependencies {
   // ...
 
-  implementation("com.apollographql.apollo3:apollo-ast:4.0.0-rc.1")
+  implementation("com.apollographql.apollo:apollo-ast:4.0.0-rc.1")
 }
 ```
 

docs/source/advanced/compiler-plugins.mdx

@@ -33,7 +33,7 @@ plugins {
 
 dependencies {
   // Add apollo-compiler as a dependency
-  implementation("com.apollographql.apollo3:apollo-compiler:4.0.0-rc.1")  
+  implementation("com.apollographql.apollo:apollo-compiler:4.0.0-rc.1")  
 }
 ```
 
@@ -42,10 +42,10 @@ Next create your plugin in a `src/main/kotlin/mypackage/MyPlugin` file:
 ```kotlin
 package mypackage
 
-import com.apollographql.apollo3.compiler.OperationOutputGenerator
-import com.apollographql.apollo3.compiler.ApolloCompilerPlugin
-import com.apollographql.apollo3.compiler.operationoutput.OperationDescriptor
-import com.apollographql.apollo3.compiler.operationoutput.OperationId
+import com.apollographql.apollo.compiler.OperationOutputGenerator
+import com.apollographql.apollo.compiler.ApolloCompilerPlugin
+import com.apollographql.apollo.compiler.operationoutput.OperationDescriptor
+import com.apollographql.apollo.compiler.operationoutput.OperationId
 
 class MyPlugin: ApolloCompilerPlugin {
   override fun operationIds(descriptors: List<OperationDescriptor>): List<OperationId> {
@@ -72,15 +72,15 @@ class MyPluginProvider: ApolloCompilerPluginProvider {
 }
 ```
 
-Make your plugin discoverable by [ServiceLoader](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html) by adding a resource in `src/main/resources/META-INF/services/com.apollographql.apollo3.compiler.ApolloCompilerPluginProvider`. This file contains the fully qualified name of your plugin: 
+Make your plugin discoverable by [ServiceLoader](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html) by adding a resource in `src/main/resources/META-INF/services/com.apollographql.apollo.compiler.ApolloCompilerPluginProvider`. This file contains the fully qualified name of your plugin: 
 
 ```
 mypackage.MyPluginProvider
 ```
 
 <Note>
 
-The name of the resource file is important. It must be `com.apollographql.apollo3.compiler.ApolloCompilerPluginProvider` and be in the `META-INF/services` folder. This is how `ServiceLoader` looks up plugins at runtime.
+The name of the resource file is important. It must be `com.apollographql.apollo.compiler.ApolloCompilerPluginProvider` and be in the `META-INF/services` folder. This is how `ServiceLoader` looks up plugins at runtime.
 </Note>
 
 ## Adding a plugin to the Apollo compiler classpath
@@ -91,7 +91,7 @@ Use the `Service.plugin()` Gradle method to add the plugin to the Apollo compile
 // app/build.gradle.kts
 plugins {
   id("org.jetbrains.kotlin.jvm")
-  id("com.apollographql.apollo3")
+  id("com.apollographql.apollo")
 }
 
 apollo {
@@ -146,6 +146,6 @@ Because codegen is run in a separate classloader when using compiler plugins, it
 
 ## Other references
 
-For other plugin APIs like layout, IR, JavaPoet and KotlinPoet transforms, check out the [ApolloCompilerPlugin API docs](https://www.apollographql.com/docs/kotlin/kdoc/apollo-compiler/com.apollographql.apollo3.compiler/-apollo-compiler-plugin/index.html)
+For other plugin APIs like layout, IR, JavaPoet and KotlinPoet transforms, check out the [ApolloCompilerPlugin API docs](https://www.apollographql.com/docs/kotlin/kdoc/apollo-compiler/com.apollographql.apollo.compiler/-apollo-compiler-plugin/index.html)
 
 For more examples, check out the [integration-tests](https://github.com/apollographql/apollo-kotlin/tree/main/tests/compiler-plugins).

docs/source/advanced/experimental-websockets.mdx

@@ -15,9 +15,9 @@ Historically, WebSockets have been one of the most complex and error-prone parts
 3. Because WebSockets are long-lived connections, they are more exposed to errors and knowing when (or if) to retry is hard.
 4. Not all subscriptions happen on WebSockets. Some use [HTTP multipart](https://www.apollographql.com/docs/router/executing-operations/subscription-multipart-protocol/) for an example.
 
-Starting with 4.0.0, Apollo Kotlin provides a new `com.apollographql.apollo3.network.websocket` package containing new `WebSocketNetworkTransport` and `WebSocketEngine` implementations (instead of `com.apollographql.apollo3.network.ws` for the current implementations).
+Starting with 4.0.0, Apollo Kotlin provides a new `com.apollographql.apollo.network.websocket` package containing new `WebSocketNetworkTransport` and `WebSocketEngine` implementations (instead of `com.apollographql.apollo.network.ws` for the current implementations).
 
-The `com.apollographql.apollo3.network.websocket` implementation provides the following:
+The `com.apollographql.apollo.network.websocket` implementation provides the following:
 
 1. Defaults to the [graphql-ws](https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md) protocol, which has become the de facto standard. Using the other protocols is still possible but having a main, specified, protocol ensures we can write a good and solid test suite.
 2. Does not inherit from the old memory model design, making the code considerably simpler. In particular, `WebSocketEngine` is now event based and no attempt at flow control is done. If you buffers grow too much, your subscription fails.
@@ -34,17 +34,17 @@ After a feedback phase, the current `.ws` APIs will become deprecated and the `.
 
 ## Migration guide
 
-In simple cases where you did not configure the underlying `WsProtocol` or retry logic, the migration should be about replacing `com.apollographql.apollo3.network.ws` with `com.apollographql.apollo3.network.websocket` everywhere:
+In simple cases where you did not configure the underlying `WsProtocol` or retry logic, the migration should be about replacing `com.apollographql.apollo.network.ws` with `com.apollographql.apollo.network.websocket` everywhere:
 
 ```kotlin
 // Replace
-import com.apollographql.apollo3.network.ws.WebSocketNetworkTransport
-import com.apollographql.apollo3.network.ws.WebSocketEngine
+import com.apollographql.apollo.network.ws.WebSocketNetworkTransport
+import com.apollographql.apollo.network.ws.WebSocketEngine
 // etc...
 
 // With
-import com.apollographql.apollo3.network.websocket.WebSocketNetworkTransport
-import com.apollographql.apollo3.network.websocket.WebSocketEngine
+import com.apollographql.apollo.network.websocket.WebSocketNetworkTransport
+import com.apollographql.apollo.network.websocket.WebSocketEngine
 // etc...
 ```
 
@@ -60,7 +60,7 @@ val apolloClient = ApolloClient.Builder()
     .build()
 
 // With
-import com.apollographql.apollo3.network.websocket.*
+import com.apollographql.apollo.network.websocket.*
 
 // [...]
 

docs/source/advanced/http-engine.mdx

@@ -10,35 +10,11 @@ By default, Apollo Kotlin uses the following HTTP clients for different platform
 | JavaScript/Wasm | [fetch()](https://developer.mozilla.org/en-US/docs/Web/API/fetch) / [Node Fetch](https://www.npmjs.com/package/node-fetch) for HTTP, [Ktor](https://ktor.io/) for WebSockets |
 | iOS/MacOS       | [NSURLSesssion](https://developer.apple.com/documentation/foundation/nsurlsession)                                                                                           |
 
-
-## Ktor engine
-
-Additionally, an optional implementation based on [Ktor](https://ktor.io/) for all targets is available in the `apollo-engine-ktor` module. To use it, add the following dependency to your project:
-
-```kotlin title="build.gradle[.kts]"
-dependencies {
-  // ...
-  implementation("com.apollographql.apollo3:apollo-engine-ktor:4.0.0-rc.1")
-}
-```
-
-And configure your `ApolloClient` to use the Ktor engine:
-
-```kotlin
-val client = ApolloClient.Builder()
-  .serverUrl("https://example.com/graphql")
-  // Create a new Ktor engine
-  .httpEngine(KtorHttpEngine())
-  // Or, if you want to reuse an existing Ktor client
-  .ktorClient(myKtorClient)
-  .build()
-```
-
 ## Implement your own HTTP engine
 
 You can use a different HTTP client with Apollo Kotlin by creating a custom class that implements the `HttpEngine` interface.
 
-The [HttpEngine interface](https://apollographql.github.io/apollo-kotlin/kdoc/apollo-runtime/com.apollographql.apollo3.network.http/-http-engine/index.html)
+The [HttpEngine interface](https://apollographql.github.io/apollo-kotlin/kdoc/apollo-runtime/com.apollographql.apollo.network.http/-http-engine/index.html)
 defines two functions: `execute` and `close`. Here's an example implementation that also includes a couple of helper
 methods:
 
@@ -89,7 +65,7 @@ This example uses an asynchronous `wrappedClient` that runs the network request
 
 ### Using your `HttpEngine`
 
-After you create your `HttpEngine` implementation, you can register it with your [`ApolloClient`](https://apollographql.github.io/apollo-kotlin/kdoc/apollo-runtime/com.apollographql.apollo3/-apollo-client/index.html) instance using [`ApolloClient.Builder.httpEngine`](https://apollographql.github.io/apollo-kotlin/kdoc/apollo-runtime/com.apollographql.apollo3/-apollo-client/-builder/http-engine.html):
+After you create your `HttpEngine` implementation, you can register it with your [`ApolloClient`](https://apollographql.github.io/apollo-kotlin/kdoc/apollo-runtime/com.apollographql.apollo/-apollo-client/index.html) instance using [`ApolloClient.Builder.httpEngine`](https://apollographql.github.io/apollo-kotlin/kdoc/apollo-runtime/com.apollographql.apollo/-apollo-client/-builder/http-engine.html):
 
 ```kotlin
 // Use your HttpEngine
@@ -101,6 +77,11 @@ val client = ApolloClient.Builder()
 
 With this configuration, Apollo Kotlin sends all of its GraphQL operation requests with `MyHttpEngine`.
 
+
+## Ktor engine
+
+An implementation of `HttpEngine` based on [Ktor](https://ktor.io/) is available in [apollographql/apollo-kotlin-ktor-support](https://github.com/apollographql/apollo-kotlin-ktor-support)
+
 ## Other HTTP customizations
 
 Besides implementing `HttpEngine`, Apollo Kotlin also supports other methods for customizing HTTP behavior:

docs/source/advanced/multi-modules.mdx

@@ -76,7 +76,7 @@ apollo {
 
 <ExperimentalFeature>
 
-The `bidirectional` parameter is experimental because it may break <a href="https://docs.gradle.org/current/userguide/build_environment.html">Gradle project isolation</a>. For a project-isolation compatible method, try <a href="https://www.apollographql.com/docs/kotlin/kdoc/apollo-gradle-plugin-external/com.apollographql.apollo3.gradle.api/-service/is-a-dependency-of.html">isADependencyOf</a> 
+The `bidirectional` parameter is experimental because it may break <a href="https://docs.gradle.org/current/userguide/build_environment.html">Gradle project isolation</a>. For a project-isolation compatible method, try <a href="https://www.apollographql.com/docs/kotlin/kdoc/apollo-gradle-plugin-external/com.apollographql.apollo.gradle.api/-service/is-a-dependency-of.html">isADependencyOf</a> 
 
 </ExperimentalFeature>
 

docs/source/advanced/network-connectivity.mdx

@@ -13,7 +13,7 @@ Android and Apple targets provide APIs to monitor the network state of your devi
 - [ConnectivityManager](https://developer.android.com/training/monitoring-device-state/) on Android targets.
 - [NWPathMonitor](https://developer.apple.com/documentation/network/nwpathmonitor) on Apple targets.
 
-You can configure your [ApolloClient](https://www.apollographql.com/docs/kotlin/kdoc/apollo-runtime/com.apollographql.apollo3/-apollo-client/index.html) to use these APIs to improve latency of your requests using the `NetworkMonitor` API:
+You can configure your [ApolloClient](https://www.apollographql.com/docs/kotlin/kdoc/apollo-runtime/com.apollographql.apollo/-apollo-client/index.html) to use these APIs to improve latency of your requests using the `NetworkMonitor` API:
 
 ```kotlin
 // androidMain
@@ -25,7 +25,7 @@ val networkMonitor = NetworkMonitor()
 // commonMain
 val apolloClient = ApolloClient.Builder()
     .serverUrl("https://example.com/graphql")
-    .networkMonitor(networkMonitor)
+    .retryOnErrorInterceptor(RetryOnErrorInterceptor(networkMonitor))
     .build()
 ```
 
@@ -54,10 +54,7 @@ When a `NetworkMonitor` is configured, `retryOnError` uses `NetworkMonitor.waitF
 
 ### Customizing the retry algorithm
 
-You can customize the retry algorithm further by defining you won interceptor. Make sure to:
-
-- add your interceptor last, so that it wraps the network call and doesn't get cache misses or any other errors that may be emitted by upstream interceptors.
-- call `retryOnError(false)` when forwarding the request downstream so that the retry is not made twice.
+You can customize the retry algorithm further by defining you own interceptor:
 
 ```kotlin
 internal class MyRetryInterceptor(private val networkMonitor: NetworkMonitor?): ApolloInterceptor {