docs: add v11/v12 migration guides and version guidance

Author: gastonfournier

README.md

@@ -8,9 +8,13 @@ Unleash is a private, secure, and scalable [feature management platform](http
 
 You can use this client with [Unleash Enterprise](https://www.getunleash.io/pricing?utm_source=readme&utm_medium=java) or [Unleash Open Source](https://github.com/Unleash/unleash).
 
->  **Migrating to v10**
+>  **Migration guides**
 >
-> If you're using `MoreOperations`, custom or fallback strategies, subscribers or bootstrapping, please see the full [migration guide](v10_MIGRATION_GUIDE.md) for details. If you use GraalVM or Quarkus, please hold off on upgrading to v10, support is planned but not implemented.
+> - [Migrating to v10](v10_MIGRATION_GUIDE.md)
+> - [Migrating to v11](v11_MIGRATION_GUIDE.md)
+> - [Migrating to v12](v12_MIGRATION_GUIDE.md)
+>
+> For ongoing updates, prefer v12. The latest patch releases of v10, v11, and v12 are currently aligned on the same optimized implementation path.
 
 ## Java Version Compatibility
 

v10_MIGRATION_GUIDE.md

@@ -2,6 +2,17 @@
 
 This guide highlights the key changes you need to be aware of when upgrading to v10.0.0 of the Unleash client.
 
+## Version guidance
+
+For ongoing updates, prefer v12.
+
+The latest patch releases in v10, v11, and v12 are currently aligned on the same optimized
+implementation path.
+
+Early v11 introduced a WASM-engine direction that we later reverted in v11 patch releases.
+
+If you need to stay on a specific major version, make sure you run the latest patch in that major.
+
 ## Custom bootstrapping
 
 The Bootstrapping interface now requires an `Optional<String>` to be returned rather than a `String`. If the bootstrapper fails to load the feature set, return an `Optional` of empty.

v11_MIGRATION_GUIDE.md

@@ -0,0 +1,22 @@
+# Migrating to Unleash-Client-Java 11.x
+
+This guide highlights what to know when upgrading from v10 to v11.
+
+## Java runtime requirement
+
+v11 requires Java 11+.
+
+## Migration path
+
+For API-level migration details, refer to the v10 guide:
+[v10_MIGRATION_GUIDE.md](v10_MIGRATION_GUIDE.md)
+
+The latest patch releases in v10, v11, and v12 are currently aligned on the same optimized
+implementation path.
+
+Early v11 introduced a WASM-engine direction that we later reverted in v11 patch releases.
+
+## Recommendation
+
+v11 is maintained for stability and critical fixes when needed, but for ongoing updates and new
+improvements, prefer v12.

v12_MIGRATION_GUIDE.md

@@ -0,0 +1,22 @@
+# Migrating to Unleash-Client-Java 12.x
+
+This guide highlights what to know when upgrading from v11 to v12.
+
+## Java runtime requirement
+
+v12 requires Java 11+.
+
+## Migration path
+
+For API-level migration details that still apply, refer to the v10 guide:
+[v10_MIGRATION_GUIDE.md](v10_MIGRATION_GUIDE.md)
+
+For current guidance on the v11 line, refer to:
+[v11_MIGRATION_GUIDE.md](v11_MIGRATION_GUIDE.md)
+
+The latest patch releases in v10, v11, and v12 are currently aligned on the same optimized
+implementation path.
+
+## Recommendation
+
+Use v12 for ongoing updates and future improvements.