Backwards Compatibility

Boost libraries generally have a large and diverse user base. To ensure successful transitions from old APIs to newer APIs under those circumstances, library authors are encouraged to follow a few guidelines when introducing breaking changes in their library:

  1. Non-breaking changes can be done without restriction.

  2. Small breaking changes can be made, but users should be given notice a few releases before the change is published. Most breaking changes fall into this category.

  3. For large breaking changes with a migration path from the old API to the new API (for example Boost.Filesystem v2 to v3), the new API should be introduced in a separate directory/namespace, and users should be noticed and given a few releases to move over. The old API can be removed after some time.

  4. For large breaking changes without a migration path (for example Boost.Spirit v2 to v3), the new API should be provided in a separate directory/namespace, and the old API should be preserved (because there’s no migration path). Removing the API should be considered the same as removing a Boost library, which can be done but needs a more extensive deprecation period.

  5. Large breaking changes that are equivalent to a redesign or rewrite of the library should be treated as a new library and a formal review (or at least a mini review) is encouraged.

Edit this Page