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. We use preview features as means of sharing our work with the community early and to get feedback on how to develop them further, without being hamstrung by our strict backwards compatibility guarantees.

We deliver preview features to the same standard of quality as the rest of Timefold Solver. However, their APIs and behavior 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.

Preview features often live in the preview.api package, and they are:

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 are an active research project. It intends 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 internal 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.