Backwards compatibility

Timefold Solver separates its API from its implementation:

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
- 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 for a new major version are clearly documented in the upgrade recipe.

Preview features

Timefold Solver includes several components which are only available as preview features. These are in preview.api packages. These are:

Diversified Late Acceptance acceptor
Solution diff API in the ai.timefold.solver.core.preview.api.domain.solution.diff package, and in the SolutionManager
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 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 Timefold Solver Github.

Experimental status of Move Streams

Move Streams, although marked as a preview feature, is an active research project. It is intended to simplify the creation of custom moves, eventually replacing move selectors. The component is under heavy development, entirely undocumented, and many key features are yet to be delivered. Neither the API nor the feature set are complete, and any part can change or be removed at any time.

Move Streams will eventually stabilize and be promoted from a research project to a true preview feature. We only expose it now to be able to use it for experimentation and testing. As such, it is an exception to the rule — this preview feature is not finished, and it is not yet ready for feedback.