docs: split up automatic and manual upgrade from OptaPlanner

Author: ge0ffrey

docs/src/modules/ROOT/pages/upgrading-timefold-solver/backwards-compatibility.adoc

@@ -5,50 +5,39 @@
 
 Timefold Solver separates its API from its implementation:
 
-* **Public API**: All classes in the following package namespaces are 100% *backwards compatible* in future releases,
-especially minor and hotfix releases:
+* **Public API**: All classes under these `api` and `config` namespaces are 100% *backwards compatible* in future minor and hotfix releases:
 ** `ai.timefold.solver.core.api`
 ** `ai.timefold.solver.benchmark.api`
 ** `ai.timefold.solver.test.api`
-** `ai.timefold.solver...api*`
-* **Configuration**: The solver configuration is backwards compatible for all elements,
-except for elements that require the use of non-public API classes.
-The solver configuration is defined by the classes in the following package namespaces:
+** `ai.timefold.solver.*.api`
 ** `ai.timefold.solver.core.config`
 ** `ai.timefold.solver.benchmark.config`
 * **Implementation classes**: All other classes are _not_ backwards compatible.
 They will change in future major or minor releases,
 but probably not in hotfix releases.
 
-Backwards incompatible changes will be clearly documented in xref:upgrading-timefold-solver/upgrade-to-latest-version.adoc#manualUpgrade[the upgrade recipe].
-
-
-[NOTE]
-====
-This documentation covers some `impl` classes too.
-Those documented `impl` classes are reliable and safe to use (unless explicitly marked as experimental in this documentation),
-but we're just not entirely comfortable yet to write their signatures in stone.
-====
+Backwards incompatible changes for a new major version are clearly documented in xref:upgrading-timefold-solver/upgrade-to-latest-version.adoc#manualUpgrade[the upgrade recipe].
 
 [#previewFeatures]
 == Preview features
 
 Timefold Solver includes several components which are only available as preview features.
+These are in `preview.api` packages.
 These are:
 
-- xref:optimization-algorithms/local-search.adoc#diversifiedLateAcceptance[Diversified Late Acceptance] acceptor.
+- xref:optimization-algorithms/local-search.adoc#diversifiedLateAcceptance[Diversified Late Acceptance] acceptor
 - xref:constraints-and-score/understanding-the-score.adoc#solutionDiff[Solution diff API]
 in the `ai.timefold.solver.core.preview.api.domain.solution.diff` package,
-and in the `SolutionManager`.
+and in the `SolutionManager`
 - _Move Streams API_ in the `ai.timefold.solver.core.preview.api.move` package
 and the `ai.timefold.solver.core.preview.api.domain.metamodel` package,
-as well as in their subpackages.
-- _Timefold Solver for Python_, which is currently in beta.
+as well as in their subpackages
+- _Timefold Solver for Python_, which is currently in beta
 
 These preview features are developed to the same standard as the rest of Timefold Solver.
 However, their APIs are not yet considered stable, pending user feedback.
 Any class, method or field related to these features may change or be removed without prior notice,
-although we will strive to avoid this as much as possible.
+although we strive to avoid this as much as possible.
 
 We encourage you to try these preview features and give us feedback on your experience with them.
 Please direct your feedback to

docs/src/modules/ROOT/pages/upgrading-timefold-solver/upgrade-from-optaplanner.adoc

@@ -6,10 +6,12 @@
 :icons: font
 
 In spring of 2024, Red Hat announced https://access.redhat.com/articles/7060671[end of life for OptaPlanner].
-Timefold Solver is a faster, feature-rich, and actively developed fork of OptaPlanner.
+Timefold Solver is a faster, feature-rich, and actively developed fork of OptaPlanner by the same team.
 
-Upgrading from OptaPlanner to Timefold Solver Community Edition only takes two minutes.
-Run the command below to upgrade your code automatically.
+== Automatic upgrade
+
+Upgrading from OptaPlanner to Timefold Solver only takes two minutes.
+Run the command below to upgrade your java, build and other code automatically.
 
 [tabs]
 ====
@@ -39,6 +41,12 @@ If it doesn't work, just revert it instead and
 https://github.com/timefoldai/timefold-solver/issues[submit an issue].
 We'll fix it with the highest priority.
 
+Timefold Solver 1.x does not support `scoreDRL`, nor is it upgraded automatically.
+If you're still using `scoreDRL` from OptaPlanner 7.x,
+please link:https://timefold.ai/blog/2023/migrating-score-drl-to-constraint-streams/[upgrade to Constraint Streams first].
+
+== Manual upgrade
+
 Timefold Solver 1.x is backward compatible with OptaPlanner 8.x,
 except for the following changes:
 
@@ -58,9 +66,3 @@ except for the following changes:
 * The unsecure module `persistence-xstream` is removed, because of old, unresolved CVEs in XStream.
 * The deprecated, undocumented `ScoreHibernateType` has been removed because of Jakarta.
 Use JPA's `ScoreConverter` instead.
-
-Timefold Solver 1.x does not support `scoreDRL`, nor is it upgraded automatically.
-If you're still using `scoreDRL` from OptaPlanner 7.x,
-please link:https://timefold.ai/blog/2023/migrating-score-drl-to-constraint-streams/[upgrade to Constraint Streams first].
-
-All other deprecated code remains to make upgrading easy.