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.