anchor.diff:  //We currently intend to support a minimal version of Java 11 throughout the entire 8.x series.
   
   
  +[.upgrade-recipe-minor.upgrade-recipe-public-api]
  +=== Refrain from using Java serialization
  +
  +Java serialization is
  +https://cr.openjdk.java.net/~briangoetz/amber/serialization.html[considered by its authors to be poorly designed] and it was suggested that the capability would, at some point in time, be removed from the platform altogether.
  +In OptaPlanner 8, we have removed most uses of the `Serializable` marker interface from the public API and we encourage users to
  +https://docs.optaplanner.org/latest/optaplanner-docs/html_single/index.html#integrationWithPersistentStorage[serialize
  +via JSON or other formats].
  +
  +[.upgrade-recipe-major.upgrade-recipe-public-api]
  +=== `SolverFactory.getScoreDirectorFactory()` replaced by `ScoreManager`
  +
  +In version 7 of OptaPlanner, using `ScoreDirectorFactory` was necessary in order to
  +https://docs.optaplanner.org/latest/optaplanner-docs/html_single/index.html#explainingTheScore[explain the score].
  +In version 8, we have added new functionality to the `ScoreManager` and as a result, there is no longer any reason to create new instances of `ScoreDirector`.
  +
  +Before in `*.java`:
  +
  +[source,java]
  +----
  +ScoreDirectorFactory<CloudBalance> scoreDirectorFactory = solverFactory.getScoreDirectorFactory();
  +try (ScoreDirector<CloudBalance> scoreDirector = scoreDirectorFactory.buildScoreDirector()) {
  +    scoreDirector.setWorkingSolution(solution);
  +    Score score = scoreDirector.calculateScore();
  +}
  +----
  +
  +After in `*.java`:
  +
  +[source,java]
  +----
  +ScoreManager<CloudBalance> scoreManager = ScoreManager.create(solverFactory);
  +Score score = guiScoreDirector.updateScore(solution);
  +----
  +
  +Methods that allowed users to retrieve an instance of `ScoreDirector` and `ScoreDirectorFactory` have been removed from public API without replacement.
  +A reduced version of the `ScoreDirector` interface was promoted to public API as part of promoting the
  +`ProblemFactChange` interface to public API.
  +
  +[.upgrade-recipe-major.upgrade-recipe-public-api]
  +=== `SolverFactory` and `PlannerBenchmarkFactory` no longer support KIE containers
  +
  +With OptaPlanner's move towards Kogito, the KIE container concept no longer applies.
  +Therefore, `SolverFactory` no longer allows to create `Solver` instances from KIE containers.
  +Likewise for `PlannerBenchmarkFactory` and benchmarks.
  +
  +Users are encouraged to check out our
  +https://github.com/kiegroup/kogito-examples/tree/master/process-optaplanner-quarkus[OptaPlanner Kogito quickstart]
  +to see how to integrate with processes in a modern, cloud-native way.
  +
   [.upgrade-recipe-major.upgrade-recipe-public-api]
   === OSGi metadata removed
   
  -==== Reason:
  -Due to the limited usage of OSGi and the maintenance burden it brings,
  -the OptaPlanner jars in the 8.x series no longer include OSGi metadata in their `META-INF/MANIFEST.MF` file.
  +Due to the limited usage of OSGi and the maintenance burden it brings, the OptaPlanner jars in the 8.x series no longer include OSGi metadata in their `META-INF/MANIFEST.MF` file.
   
   [.upgrade-recipe-minor]
   === `filterClassList` replaced by a single filterClass
   
  -The configuration of `EntitySelector`, `ValueSelector` and `MoveSelector` now has a single filter class in both
  -the configuration API and the solver configuration XML.
  -
  -==== Reason:
  -In practice, you don't need multiple selection filter classes often, and you can always replace them by a single selection
  -filter class which implements the logic of all of them.
  +The configuration of `EntitySelector`, `ValueSelector` and `MoveSelector` now has a single filter class in both the configuration API and the solver configuration XML.
  +
  +In practice, you don't need multiple selection filter classes often, and you can always replace them by a single selection filter class which implements the logic of all of them.
   Passing a single selection class now requires less boilerplate code.
   
   Before in `*.java`:
  -[source, java]
  +
  +[source,java]
   ----
   ValueSelectorConfig valueSelectorConfig = new ValueSelectorConfig();
   valueSelectorConfig.setFilterClassList(Collections.singletonList(MySelectionFilterClass.class));
   ----
   
   After in `*.java`:
  -[source, java]
  +
  +[source,java]
   ----
   ValueSelectorConfig valueSelectorConfig = new ValueSelectorConfig();
   valueSelectorConfig.setFilterClass(MySelectionFilterClass.class);
  
positive.code: 
  After in `*.xml`:
  
  [source, xml]
  ----
  <swapMoveSelector>
    <variableNameIncludes>
  
negative.code: 
  Before in `*.xml`:
  
  [source,xml]
  ----
  <swapMoveSelector>
    <entitySelector>
  