Re: [boost] Policy for breaking changes

Subject: Re: [boost] Policy for breaking changes
From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2017-12-03 13:00:43

On 12/03/17 00:44, Louis Dionne via Boost wrote:
> Hi all,
> 
> So far, I've been careful about not doing any breaking changes to Hana.
> Hana obeys semantic versioning, and I'm accumulating desirable breaking
> changes until I'm ready to publish a new major version.
> 
> I'm wondering what's the policy for major breaking changes with Boost
> libraries. For example, let's say I wanted to do an update of Hana with
> C++17 features; this would be a large breaking change, with all kinds
> of API changes, etc..
> 
> - Are such drastic changes prohibited altogether? Or perhaps they’re not
>    prohibited but there’s historical evidence showing it’s always a bad
>    idea?
> - Do such changes require going through a mini review?
> - Is it customary to leave the old version of the library there in a
>    separate directory (or put the new one in a separate directory)?
>    I think Spirit does that, e.g. Spirit Classic is still available IIRC.
> 
> I think I know the answer to these questions from observing other author's
> behavior, but I'd like to see what the community thinks about this. It has
> an impact on the Boost libraries as a whole, since a major breaking change
> in one library could prevent users from updating Boost as a whole, which
> has an impact on all of us.
> 
> I'm looking forward to hearing other people's thoughts on the matter.

Generally, as you probably know, autors are encouraged to avoid breaking 
changes and if those are necessary, provide a deprecation period of a 
few Boost releases for the users to migrate. This is how it was with 
Boost.Filesystem, for example, which provided both v2 and v3 for several 
releases, with users being able to pick the API they need. Later, v2 was 
removed.

However, the important point is, IMHO, whether users have a clear 
migration path. Boost.Filesystem v2 and v3 both supported C++03 and the 
difference between the API was not too drastic, so users had little 
problem to update their code. Boost.Spirit v1 (a.k.a. Classic) and v2 
also both support C++03, but the difference in the API is more 
significant, so the authors decided to keep v1 around. Spirit x3 will 
also bump the minimum C++ version, so I'm quite sure v2 will also stay 
available when x3 is out.

So the bottom line is:

1. If your changes can be made backward-compatible (i.e. the C++17 
features you want to use can be made optional), this would be preferred. 
This would allow C++14 users that currently use Boost.Hana to continue 
using it.

2. If you want to make backward-incompatible changes but the changes 
don't require major rewrites of users' code and you can still provide 
support for C++14 then you should provide a deprecation period and allow 
the users to select the version of the API they want to use. After a few 
Boost release you can remove the deprecated code.

3. If you want the C++17 version to be significantly different from the 
current version then the users will not have a clear migration path 
(C++17 may not be available to them). In this case I would suggest 
adding this new library version as Boost.Hana2 and keeping Boost.Hana 
available.

As for the review, this is your choice, but I think at least a 
mini-review for Boost.Hana2 would be useful, both for you and your users.