On February 9, 2018 7:07:29 PM EST, Daniel James via Boost wrote:

...

Folks,

In early December 2017, there was a thread asking for guidelines regarding breaking changes: [1]. The conclusion reached in that thread seemed to be agreed upon [2] and I suggested making it part of the library guidelines. I have finally submitted a PR [3] to add it to the library _guidelines_ (not _requirements_). Feel free to take a look at the PR and chime in as

On 9 February 2018 at 21:32, Louis Dionne via Boost wrote: this

...

concerns everyone.

I merged the PR into the beta site, so you can see it there: https://beta.boost.org/development/requirements.html#Backwards_compatibility

Thanks for floating these guidelines. There are seemingly three bullets that apply to large changes and one for small changes, which is a little odd. I realize there are distinctions, but using bullets doesn't work that well. I'd also use active voice and remove the commentary. Here's my take: "To ensure a successful transition from old to new APIs, library authors are encouraged to follow the following guidelines when introducing breaking changes in a library according to the impact of those changes. "Minor breaking changes are the easiest for users to adapt to. Give users notice for several releases before publishing such changes. "Large breaking changes require more care. If there is a migration path from the old API to the new (for example from Boost.Filesystem v2 to v3), introduce the new API in a separate directory and/or namespace. Give users a few releases to make the change, after which you can remove the old API. "For large breaking changes without a migration path (for example, Boost.Spirit v2 to v3), provide the new API in a new directory and namespace, and preserve the old API. Treat removing the old API the same as removing a Boost library, which requires a significant deprecation period. "If the changes are equivalent to a redesign or rewrite of the library, treat them as a new library. A formal review, or at least a mini review, is highly encouraged." -- Rob (Sent from my portable computation device.)