Backwards compatibility

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:

    • 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.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 the upgrade recipe.

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.

Preview features

Timefold Solver includes several components which are only available as preview features. 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.

  • 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.

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.

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.