Boost logo

Boost :

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

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

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.

Boost list run by bdawes at, gregod at, cpdaniel at, john at