mirror of
https://github.com/boostorg/website-v2-docs.git
synced 2026-01-19 04:42:17 +00:00
23 lines
1.7 KiB
Plaintext
23 lines
1.7 KiB
Plaintext
////
|
|
Copyright (c) 2024 The C++ Alliance, Inc. (https://cppalliance.org)
|
|
|
|
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
|
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
|
|
|
Official repository: https://github.com/boostorg/website-v2-docs
|
|
////
|
|
= Backwards Compatibility
|
|
:navtitle: 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:
|
|
|
|
. Non-breaking changes can be done without restriction.
|
|
|
|
. 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.
|
|
|
|
. 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.
|
|
|
|
. 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.
|
|
|
|
. 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.
|