Skip to content

[docs] Tweak the v5 migration guide wording #6728

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
martinbonnin merged 1 commit into from
Oct 3, 2025
Merged

[docs] Tweak the v5 migration guide wording #6728

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 5 additions & 11 deletions docs/source/migration/5.0.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,12 @@
description: Learn how to migrate from version 4 with key changes, new features, and tools designed for improved stability and maintainability. Follow step-by-step guidance and make a seamless transition
---

Apollo Kotlin 5 is mostly binary compatible with Apollo Kotlin 4 with a few exceptions:
Apollo Kotlin 5 is an incremental evolution of Apollo Kotlin 4 and keeps the same package name.

- Symbols that were `DeprecationLevel.ERROR` in v4 are now removed.
- `apollo-compiler` has breaking changes and is generally still considered unstable with the exception of persisted queries compiler plugins:
- `ApolloCompilerPlugin.beforeCompilationStep()`, `ApolloCompilerRegistry.registerOperationIdsGenerator()` and dependent symbols are stable and will go through the usual deprecation cycle if they ever need to change.
- The APIs used by the data builders generated sources (`buildData`, `ObjectBuilder`, `CustomScalarAdapters.PASSTHROUGH`...) have changed. This is not an issue unless you called those APIs directly or distributed data builders code in a library. In that last case, your consumers will have to update to Apollo Kotlin 5.
- A few symbols were not supposed to be exposed and have been hidden:
- `BooleanExpression.simplify()`
- `DefaultHttpRequestComposer.HEADER_APOLLO_OPERATION_ID`
- ...
In most cases, bumping the version should be transparent. The exceptions are:

Check warning on line 9 in docs/source/migration/5.0.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/migration/5.0.mdx#L9 

The terms 'bumping the version' and 'transparent' are jargon. Use simpler, more direct language for clarity.

```suggestion
In most cases, updating the version requires no other changes. The exceptions are:
```

- Symbols that were `DeprecationLevel.ERROR` in v4 are now removed. Remove all your deprecated usages before migrating to v5.
- `apollo-compiler` is still considered experimental. You will need to update your [Apollo Compiler Plugins](https://www.apollographql.com/docs/kotlin/advanced/compiler-plugins).

Check warning on line 12 in docs/source/migration/5.0.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/migration/5.0.mdx#L12 

Use the imperative mood for instructions to make them more direct and actionable.

```suggestion
- <code>apollo-compiler</code> is still considered experimental. Update your [Apollo Compiler Plugins](https://www.apollographql.com/docs/kotlin/advanced/compiler-plugins). 
```

We tried hard to minimize the impact of the binary changes so that running code compiled for v4 will run with v5. But the occasional incompatibility may happen. In that case, the incompatible libraries will need to compile against v5 and make a new release.

Expand All @@ -35,7 +31,6 @@
}
```


## Removed `Service.operationOutputGenerator` and `Service.operationIdGenerator`

While running your `OperationOutputGenerator` directly in your build script classpath was convenient, it required the compiler code to run completely in the global buildscript classpath. This created numerous issues such as incompatible dependencies and/or unneeded build invalidations.
Expand All @@ -62,7 +57,6 @@
Read more in the [persisted queries](https://www.apollographql.com/docs/kotlin/v5/advanced/persisted-queries) and [compiler plugins](https://www.apollographql.com/docs/kotlin/v5/advanced/compiler-plugins) pages.



## Removed ApolloIdlingResource

Apollo Kotlin 5 removes `ApolloIdlingResource`. `IdlingResource` usage has been slowly decreasing and there are now better alternatives to do your testing.
Expand Down