chore(docs): clarify some breaking changes in v10 (#368)

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
 
@@ -110,21 +114,17 @@ You can also **provide an [Unleash context](https://docs.getunleash.io/reference
 
 ### Activation strategies
 
-The Java client comes with implementations for the built-in activation strategies provided by Unleash:
+The Java client supports Unleash built-in activation strategies (such as `default`, `userWithId`, `gradualRolloutRandom`, `gradualRolloutUserId`, `gradualRolloutSessionId`, `remoteAddress`, and `applicationHostname`).
 
-- DefaultStrategy
-- UserWithIdStrategy
-- GradualRolloutRandomStrategy
-- GradualRolloutUserWithIdStrategy
-- GradualRolloutSessionIdStrategy
-- RemoteAddressStrategy
-- ApplicationHostnameStrategy
+As of v10, these built-ins are evaluated by the embedded Yggdrasil engine and are not exposed as public Java strategy classes in this SDK.
 
 Read more about the strategies in the [activation strategies reference documentation](https://docs.getunleash.io/reference/activation-strategies).
 
 #### Custom strategies
-You may also specify and implement your own strategy. The specification must be registered in the Unleash UI and
-you must register the strategy implementation when you set up Unleash.
+You may also specify and implement your own strategy. The specification must be registered in the Unleash UI and you must register the strategy implementation when you set up Unleash.
+
+You can also provide a `fallbackStrategy` via `UnleashConfig` if the client receives a strategy
+name it does not recognize.
 
 ```java
 Strategy s1 = new MyAwesomeStrategy();

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.
@@ -16,6 +27,12 @@ The Bootstrapping interface now requires an `Optional<String>` to be returned ra
 
 The strategy interface has changed to only include the two methods `getName` and `isEnabled`. `isEnabled` now requires both a parameter map and an `UnleashContext`. This only affects users who are implementing custom or fallback strategies.
 
+Built-in strategy classes from `io.getunleash.strategy` (for example
+`GradualRolloutRandomStrategy`, `GradualRolloutUserWithIdStrategy`, and
+`GradualRolloutSessionIdStrategy`) are no longer part of the Java SDK public API in v10.
+
+These strategies are evaluated internally by Yggdrasil. There is no class-for-class replacement to import for built-ins; use the built-ins via Unleash configuration, and implement `Strategy` only for custom or fallback behavior.
+
 ## Events
 
 The following subscriber functions are no longer available: `togglesBackedUp`, `toggleBackupRestored`, and `togglesBootstrapped`. Subscribing to `featuresBackedUp`, `featuresBackupRestored`, and `featuresBootstrapped` respectively serves the same purpose. These subscribers no longer yield events that contain the full feature flag definition, instead, they expose a `getFeatures` method which returns a list of lightweight Java objects containing the feature name, the type of flag, and the project it's bound to.

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.