Re: [boost] [Heads up] PR adding guidelines for breaking changes on the website

Subject: Re: [boost] [Heads up] PR adding guidelines for breaking changes on the website
From: Rob Stewart (rstewart_at_[hidden])
Date: 2018-02-11 12:13:37

On February 9, 2018 7:07:29 PM EST, Daniel James via Boost <boost_at_[hidden]> wrote:
> On 9 February 2018 at 21:32, Louis Dionne via Boost
> <boost_at_[hidden]> 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
> 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.)