4.3 changelog and compiler plugins documentation (#6556)

* Add Changelog for 4.3.0

* Update docs for 4.3 (#6550)

* add missing link

* fix merge

* Update CHANGELOG.md

Co-authored-by: Benoit 'BoD' Lubek <[email protected]>

* shorter syntax

* mention the new normalized cache

---------

Co-authored-by: Benoit 'BoD' Lubek <[email protected]>

Author: martinbonnin

CHANGELOG.md

@@ -3,6 +3,28 @@ Change Log
 
 # Next version
 
+# Version 4.3.0
+
+Version 4.3.0 allows adding multiple compiler plugins and stabilizes `ApolloCompilerPlugin.beforeCompilationStep()` as the main entry point for compiler plugins. Read more in the [compiler plugins documentation page](https://www.apollographql.com/docs/kotlin/advanced/compiler-plugins).
+
+This allows to move some cache-specific code generation logic to the new normalized cache repo and better separate concerns.
+
+Moving forward, `ApolloCompilerPlugin.beforeCompilationStep()` and `ApolloCompilerRegistry.registerOperationIdsGenerator()` are considered stable because they play an important part in setting up [persisted queries](https://www.apollographql.com/docs/kotlin/advanced/persisted-queries). Other APIs are considered more advanced and will most likely stay unstable for the foreseeable future. 
+
+## Contributors 💜
+
+Many thanks to @gnehz972 and @mengdd for their fixes about HTTP batching 💜
+
+## 👷‍♂️ All changes
+
+* Fix losing response headers when using batch request (#6538)
+* fix the batch size not respected issue (#6528)
+* prepare compiler plugins for 4.3 (#6549)
+* Allow to register multiple compiler plugins (#6546)
+* Add key fields to selections even when they're already selected with an alias (#6503) (#6544)
+* Ignore scalars/enums in checkCapitalizedFields (#6502) (#6543)
+* Call DocumentTransform.transform after processing (#6510) (#6512)
+
 # Version 4.2.0
 
 _2025-04-28_

docs/source/advanced/compiler-plugins.mdx

@@ -32,61 +32,36 @@ plugins {
 }
 
 dependencies {
-  // Add apollo-compiler as a dependency
-  implementation("com.apollographql.apollo:apollo-compiler:4.1.1")  
+  // Add apollo-compiler as a compileOnly dependency
+  compileOnly("com.apollographql.apollo:apollo-compiler:4.3.0")  
 }
 ```
 
 Next create your plugin in a `src/main/kotlin/mypackage/MyPlugin` file:
 
 ```kotlin
-package mypackage
-
-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> {
-    // This assumes the returned ids are in the same order as the descriptors
-    return registerOperations(descriptors).withIndex().map { OperationId(it.value, descriptors[it.index].name) }
-  }
-
-  /**
-   * Send operations to a remote server and return the server persisted ids 
-   */
-  fun registerOperations(descriptors: List<OperationDescriptor>): List<String> {
-    // ...
+  override fun beforeCompilationStep(
+      environment: ApolloCompilerPluginEnvironment,
+      registry: ApolloCompilerRegistry,
+  ) {
+    // add your custom code here
   }
 }
 ```
 
-Next, create an `ApolloCompilerPluginProvider`. This is the entry point of compiler plugins. It is loaded using the [ServiceLoader](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html) API.
-
-```kotlin
-class MyPluginProvider: ApolloCompilerPluginProvider {
-  override fun create(environment: ApolloCompilerPluginEnvironment): ApolloCompilerPlugin {
-    return MyPlugin()
-  }
-}
-```
 
-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: 
+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.ApolloCompilerPlugin`. This file contains the fully qualified name of your plugin: 
 
 ```
-mypackage.MyPluginProvider
+mypackage.MyPlugin
 ```
 
 <Note>
 
-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.
+The name of the resource file is important. It must be `com.apollographql.apollo.compiler.ApolloCompilerPlugin` and be in the `META-INF/services` folder. This is how `ServiceLoader` looks up plugins at runtime.
 </Note>
 
-<Note>
-
-Only a single plugin is supported at this time. If you need more, you can usually have a single wrapper plugin that calls your different implementations in the required order. 
-</Note>
 
 ## Adding a plugin to the Apollo compiler classpath
 
@@ -133,9 +108,14 @@ apollo {
 The arguments are available in `ApolloCompilerPluginEnvironment.arguments`:
 
 ```kotlin
-class MyPluginProvider: ApolloCompilerPluginProvider {
-  override fun create(environment: ApolloCompilerPluginEnvironment): ApolloCompilerPlugin {
-    return MyPlugin(environment.arguments.get("token") as String)
+class MyPlugin: ApolloCompilerPlugin {
+  override fun beforeCompilationStep(
+      environment: ApolloCompilerPluginEnvironment,
+      registry: ApolloCompilerRegistry,
+  ) {
+    val token = environment.arguments.get("token") as String
+    
+    // add your custom code here
   }
 }
 ```

docs/source/advanced/persisted-queries.mdx

@@ -108,10 +108,16 @@ The `Plugin` interface has an `operationIds()` method that you can override to c
 Example Md5 hash generator:
 
 ```kotlin
-class MyPlugin: Plugin {
-  override fun operationIds(descriptors: List<OperationDescriptor>): List<OperationId> {
-    return descriptors.map { OperationId(it.source.md5(), it.name) }
+class MyPlugin : ApolloCompilerPlugin {
+  override fun beforeCompilationStep(
+      environment: ApolloCompilerPluginEnvironment,
+      registry: ApolloCompilerRegistry,
+  ) {
+    registry.registerOperationIdsGenerator {
+      it.map { OperationId(it.source.md5(), it.name) }
+    }
   }
 }
+
 ```