Policy for breaking changes
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. Thanks, Louis
On 12/2/2017 4:44 PM, 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.
If the breaking change is not part of the private API usually you notify end-users for at least one Boost release, before making the change in a subsequent Boost release. This also includes C++ level requirements. If the breaking change is private, then no matter what it is I see that as something the maintainer of a library can do at any time. As far as providing major changes to non-private functionality as a whole new "release" of the library, then it is up to the maintainer if he wants to still provide a backward compatibility layer. But once again, whatever the decision, if the end-user has to do something differently to use the library as he did before, I think my first paragraph answer should still be in effect.
Thanks, Louis
On Sat, Dec 2, 2017 at 10:52 PM, Edward Diener via Boost <boost@lists.boost.org> wrote:
If the breaking change is not part of the private API usually you notify end-users for at least one Boost release, before making the change in a subsequent Boost release. This also includes C++ level requirements.
If the breaking change is private, then no matter what it is I see that as something the maintainer of a library can do at any time.
If it's private, how can it be a breaking change?
As far as providing major changes to non-private functionality as a whole new "release" of the library, then it is up to the maintainer if he wants to still provide a backward compatibility layer. But once again, whatever the decision, if the end-user has to do something differently to use the library as he did before, I think my first paragraph answer should still be in effect.
Thanks, Louis
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
-- Olaf
I'm looking forward to hearing other people's thoughts on the matter.
Boost.Hana2 Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/
On Sat, Dec 2, 2017 at 6:33 PM, Niall Douglas via Boost < boost@lists.boost.org> wrote:
I'm looking forward to hearing other people's thoughts on the matter.
Boost.Hana2
That was a joke, right? -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net
On 03/12/2017 02:37, Rene Rivera via Boost wrote:
On Sat, Dec 2, 2017 at 6:33 PM, Niall Douglas via Boost < boost@lists.boost.org> wrote:
I'm looking forward to hearing other people's thoughts on the matter.
Boost.Hana2
That was a joke, right?
Louis said:
this would be a large breaking change, with all kinds of API changes
That's obviously a Boost.Hana2. No joke. Not sure why you thought that. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/
On Sun, Dec 3, 2017 at 6:07 AM, Niall Douglas via Boost < boost@lists.boost.org> wrote:
On 03/12/2017 02:37, Rene Rivera via Boost wrote:
On Sat, Dec 2, 2017 at 6:33 PM, Niall Douglas via Boost < boost@lists.boost.org> wrote:
I'm looking forward to hearing other people's thoughts on the matter.
Boost.Hana2
That was a joke, right?
Louis said:
this would be a large breaking change, with all kinds of API changes
That's obviously a Boost.Hana2. No joke. Not sure why you thought that.
Because if it's a big enough change to require a new library module.. It should also require an entirely new name.. And an entirely new review. I.e. if it's different enough it's no longer Hana. It might solve the same domain but it will do it in a different manner. -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Niall Douglas via Boost Sent: 03 December 2017 01:33 To: boost@lists.boost.org Cc: Niall Douglas Subject: Re: [boost] Policy for breaking changes
I'm looking forward to hearing other people's thoughts on the matter.
Boost.Hana2
+1 This gives *you* max freedom. And *users* min hassle and/or FUD. But it's a fine judgement and I don't really have a sense of the impact of the breaking changes on the users in this case. Paul PS Also +1 for updating Boost guidelines as Louis suggests. --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
"Paul A. Bristow via Boost" wrote in message news:011601d36d29$39719c70$ac54d550$@hetp.u-net.com...
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Niall Douglas via Boost Sent: 03 December 2017 01:33 To: boost@lists.boost.org Cc: Niall Douglas Subject: Re: [boost] Policy for breaking changes
I'm looking forward to hearing other people's thoughts on the matter.
Boost.Hana2
+1
+1 We have already Boost.Coroutine and Boost.Coroutine2 and Boost.Signals and Boost.Signals2 (Boost.Coroutine and Boost.Signals are now deprecated). There was also a breaking change in Boost.Coroutine between 1.54.0 and 1.55.0 which I found annoying (the change was documented in the release notes; I would prefer upgrading though without breaking code - possible now thanks to Boost.Coroutine2). Boris
On 4 December 2017 at 15:44, Boris Schäling via Boost <boost@lists.boost.org
wrote:
I would prefer upgrading though without breaking code - possible now thanks to Boost.Coroutine2).
The best thing would indeed be to stick to c++98 and be done with it... All this new stuff (what *are* they thinking?), it's a pita and you actually have to try and master it (and that takes effort), so bullocks... degski -- "*Ihre sogenannte Religion wirkt bloß wie ein Opiat reizend, betäubend, Schmerzen aus Schwäche stillend.*" - Novalis 1798
Degski wrote:
The best thing would indeed be to stick to c++98 and be done with it... All this new stuff (what *are* they thinking?), it's a pita and you actually have to try and master it (and that takes effort), so bullocks...
Bah! Who needs these newfangled automated weaving looms anyway? :) On 4 December 2017 at 23:19, degski via Boost <boost@lists.boost.org> wrote:
On 4 December 2017 at 15:44, Boris Schäling via Boost < boost@lists.boost.org
wrote:
I would prefer upgrading though without breaking code - possible now thanks to Boost.Coroutine2).
The best thing would indeed be to stick to c++98 and be done with it... All this new stuff (what *are* they thinking?), it's a pita and you actually have to try and master it (and that takes effort), so bullocks...
degski -- "*Ihre sogenannte Religion wirkt bloß wie ein Opiat reizend, betäubend, Schmerzen aus Schwäche stillend.*" - Novalis 1798
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/ mailman/listinfo.cgi/boost
"Paul A. Bristow via Boost" wrote in message news:011601d36d29$39719c70$ac54d550$@hetp.u-net.com...
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Niall Douglas via Boost Sent: 03 December 2017 01:33 To: boost@lists.boost.org Cc: Niall Douglas Subject: Re: [boost] Policy for breaking changes
I'm looking forward to hearing other people's thoughts on the matter.
Boost.Hana2
+1
+1 We have already Boost.Coroutine and Boost.Coroutine2 and Boost.Signals and Boost.Signals2 (Boost.Coroutine and Boost.Signals are now deprecated). There was also a breaking change in Boost.Coroutine between 1.54.0 and 1.55.0 which I found annoying (the change was documented in the release notes; I would prefer upgrading though without breaking code - possible now thanks to Boost.Coroutine2). Boris
"Paul A. Bristow via Boost" wrote in message news:011601d36d29$39719c70$ac54d550$@hetp.u-net.com...
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Niall Douglas via Boost Sent: 03 December 2017 01:33 To: boost@lists.boost.org Cc: Niall Douglas Subject: Re: [boost] Policy for breaking changes
I'm looking forward to hearing other people's thoughts on the matter.
Boost.Hana2
+1
+1 We have already Boost.Coroutine and Boost.Coroutine2 and Boost.Signals and Boost.Signals2 (Boost.Coroutine and Boost.Signals are now deprecated). There was also a breaking change in Boost.Coroutine between 1.54.0 and 1.55.0 which I found annoying (the change was documented in the release notes; I would prefer upgrading though without breaking code - possible now thanks to Boost.Coroutine2). Boris
Le 02/12/2017 à 22:44, Louis Dionne via Boost a écrit :
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.
Hi Louis, do you want to break the users code with your changes? I don't believe, you could want it. do you want to maintain two versions of your library? If yes, do you want to require that all the parts of an application uses the same library version? I suggest to don't do that, you will lost users. If you want to make it possible to have two version of Boost.Hana, I believe the best is to take a new folder and a new namespace, as Boost.Spirit. I've not do that. I did a really bad work with Boost.Thread/Chrono and I'm paying for it. I don't think we are requiring a review for each major version change, but if you consider that the library changes is a redesign, it would be a good idea to have a review. Vicente
On 12/03/2017 02:18 AM, Vicente J. Botet Escriba via Boost wrote:
Le 02/12/2017 à 22:44, Louis Dionne via Boost a écrit :
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.
Hi Louis,
do you want to break the users code with your changes? I don't believe, you could want it.
do you want to maintain two versions of your library?
If yes, do you want to require that all the parts of an application uses the same library version? I suggest to don't do that, you will lost users.
If you want to make it possible to have two version of Boost.Hana, I believe the best is to take a new folder and a new namespace, as Boost.Spirit.
I've not do that. I did a really bad work with Boost.Thread/Chrono and I'm paying for it.
Spirit did something like that. It has an x3 version and a qi version of it's code. The x3 version is used with: #include <boost/spirit/home/x3.hpp> I don't know how well that went. One thing to guard against is to make sure you don't duplicate #include guards. Spirit x3 didn't and that led to minor problems when trying to use the qi as well as the x3 versions of code :( -regards, Larry
Boost - Dev mailing list wrote
Le 02/12/2017 à 22:44, Louis Dionne via Boost a écrit :
Hi all,
[...]
I'm looking forward to hearing other people's thoughts on the matter.
Hi Louis,
do you want to break the users code with your changes? I don't believe, you could want it.
do you want to maintain two versions of your library?
If yes, do you want to require that all the parts of an application uses the same library version? I suggest to don't do that, you will lost users.
If you want to make it possible to have two version of Boost.Hana, I believe the best is to take a new folder and a new namespace, as Boost.Spirit.
I've not do that. I did a really bad work with Boost.Thread/Chrono and I'm paying for it.
[...]
I see; so there's prior experience in simply doing significant breaking changes without preserving the older behavior in some way (e.g. new directory), and it's not working well. Thanks, that's exactly the kind of first hand experience I wanted to get. I won't fall into the same trap. Louis -- Sent from: http://boost.2283326.n4.nabble.com/Boost-Dev-f2600599.html
If possible can people attempt to remove [SPAM] from Subject: lines before replying? (I think, looking at the thread history, that this may have been added by Louis Dionne's email provider, but however it occurred the consequence is my inbox (and possibly that of others) doesn't get these messages without manual intervention.) Thanks, Roger.
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.
On 12/2/17 1:44 PM, Louis Dionne via Boost wrote:
Hi all,
So far, I've been careful about not doing any breaking changes to Hana.
I'm a little unclear what "breaking" might mean here. Here are couple of different scenarios. A change might result in any the following: a) calls into the API return exactly the same value. This would be something like a bug fix or performance enhancement. Clearly this change wouldn't break anything. b) some enhancement like a new (meta)function is made available. This updates code and documentation but doesn't break any application which uses the library. c) some change which alters the API in a way that previous applications fail to compile. Clearly this is a "breaking change". But I would argue that it's totally innocuous. Using the new version of the library trips a compile error which would mean that the library user has to update his code. He might not be really happy about this, but it's not going to cause any harm. d) silently changing what some library function does. uh-oh. Here one is going to have one testy user. I would recommend create a function/type with a new name. The old name can be removed if you want so this situation decays into c) above. Maybe not a happy user, but he suffers only a minor inconvenience. e) some change which has an effect previous usages of the library. The classic case is the serialization library where corrections/enhancements of the library code have to be done in such a way that previously made data archives are still readable. This can sometimes be a big issue. In sort, I don't see the need for something like "Hana2" unless the changes are so extensive that is effectively a whole new library. If this is the case, it raises a bunch of other questions. An example is spirit library. We have spirit, spirit1, and spirit3 which are quite incompatible with each other. Only now have I learned that spirit3 is not yet totally "ready" - after many years of being in boost. I'm wondering if such cases shouldn't be considered as a new library subject to the same review requirements as any new library would be. Finally, I see hana as very niche library which is not in wide usage in user code. So it's not clear how many people would be effected by "breaking" changes. If it were 10 people I'd say we should just let the author deal with it. If it's 100,000 people, it should be handled differently. Unfortunately, we have absolutely no useful information regarding how widely any particular library is actually being used. It would be useful to have such information for cases like this as well as for many others. Robert Ramey
On Sun, Dec 3, 2017 at 9:51 AM, Robert Ramey via Boost < boost@lists.boost.org> wrote:
Finally, I see hana as very niche library which is not in wide usage in user code. So it's not clear how many people would be effected by "breaking" changes. If it were 10 people I'd say we should just let the author deal with it. If it's 100,000 people, it should be handled differently. Unfortunately, we have absolutely no useful information regarding how widely any particular library is actually being used. It would be useful to have such information for cases like this as well as for many others.
Some information from the Conan Hana package.. < https://bintray.com/bincrafters/public-conan/Boost.Hana%3Abincrafters#statis...
.
-- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net
On 12/03/17 20:13, Rene Rivera via Boost wrote:
On Sun, Dec 3, 2017 at 9:51 AM, Robert Ramey via Boost < boost@lists.boost.org> wrote:
Finally, I see hana as very niche library which is not in wide usage in user code. So it's not clear how many people would be effected by "breaking" changes. If it were 10 people I'd say we should just let the author deal with it. If it's 100,000 people, it should be handled differently. Unfortunately, we have absolutely no useful information regarding how widely any particular library is actually being used. It would be useful to have such information for cases like this as well as for many others.
Some information from the Conan Hana package.. < https://bintray.com/bincrafters/public-conan/Boost.Hana%3Abincrafters#statis...
.
Is it supposed to show some kind of graph? I don't see any.
On Sun, Dec 3, 2017 at 12:36 PM, Andrey Semashev via Boost < boost@lists.boost.org> wrote:
On 12/03/17 20:13, Rene Rivera via Boost wrote:
On Sun, Dec 3, 2017 at 9:51 AM, Robert Ramey via Boost < boost@lists.boost.org> wrote:
Finally, I see hana as very niche library which is not in wide usage in user code. So it's not clear how many people would be effected by "breaking" changes. If it were 10 people I'd say we should just let the author deal with it. If it's 100,000 people, it should be handled differently. Unfortunately, we have absolutely no useful information regarding how widely any particular library is actually being used. It would be useful to have such information for cases like this as well as for many others.
Some information from the Conan Hana package.. < https://bintray.com/bincrafters/public-conan/Boost.Hana% 3Abincrafters#statistics
.
Is it supposed to show some kind of graph? I don't see any.
Yes, it's supposed to show a graph, that indicates there where 7 downloads in the last month. Works for me with Chrome. -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net
On 3 December 2017 at 21:00, Rene Rivera via Boost <boost@lists.boost.org> wrote:
Yes, it's supposed to show a graph, that indicates there where 7 downloads in the last month. Works for me with Chrome.
Most of boost depends on config, and there were only 441 downloads of it. That's a very small sample of boost downloads, and I suspect it's skewed towards binary packages.
On Sun, Dec 3, 2017 at 2:42 PM, Daniel James via Boost < boost@lists.boost.org> wrote:
On 3 December 2017 at 21:00, Rene Rivera via Boost <boost@lists.boost.org> wrote:
Yes, it's supposed to show a graph, that indicates there where 7
downloads
in the last month. Works for me with Chrome.
Most of boost depends on config, and there were only 441 downloads of it. That's a very small sample of boost downloads, and I suspect it's skewed towards binary packages.
Yes, it's a small sample. As it's limited to people who are using conan to obtain the modular Boost. But's it's better than no samples :-) -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net
On 12/3/17 2:02 PM, Rene Rivera via Boost wrote:
On Sun, Dec 3, 2017 at 2:42 PM, Daniel James via Boost < boost@lists.boost.org> wrote:
On 3 December 2017 at 21:00, Rene Rivera via Boost <boost@lists.boost.org> wrote:
Yes, it's supposed to show a graph, that indicates there where 7
downloads
in the last month. Works for me with Chrome.
Most of boost depends on config, and there were only 441 downloads of it. That's a very small sample of boost downloads, and I suspect it's skewed towards binary packages.
Yes, it's a small sample. As it's limited to people who are using conan to obtain the modular Boost. But's it's better than no samples :-)
Let's try to agree that it would be useful to have better information on the usage is of various C++ libraries - not restricted to Boost. Robert Ramey
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.. [...]
Thanks everyone for the feedback, it's quite useful and it crystallizes some of the expected behavior for Boost authors. Here's a summary of what I got away from the answers: 1. Non-breaking changes can be done without restriction. 2. Small breaking changes can be made, but users should be given notice a few releases before the change is published. 3. For large breaking changes WITH a migration path from before-the-change to after-the-change (e.g. filesystem v2 -> v3), the change should be made by providing the functionality in a separate directory/namespace, and users should be given a few releases to move over. The before-the-change functionality can be removed after some time. 4. For large breaking changes WITHOUT a migration path (e.g. spirit 2 -> 3), the change should be made in a separate directory/namespace, and the before-the-change state should be preserved (because there's no migration path). 5. If a large change falling into categories (3) or (4) is equivalent to a redesign or rewrite of the library, this should be treated as a new library and a formal review (or at least a mini review) is encouraged. Please correct me if I got something wrong. Would it be useful to document this officially somewhere on the Boost website? Is it desirable for Boost to adopt some kind of "official stance" on this matter (for now none of this is normative)? I can submit a PR to add the documentation if I only know what module I must submit it to. As far as Hana is concerned, I think the logical thing for me to do is to proceed by way of small breaking changes with a deprecation period, at least for the time being. Thanks! Louis -- Sent from: http://boost.2283326.n4.nabble.com/Boost-Dev-f2600599.html
On 12/04/17 06:10, 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.. [...]
Thanks everyone for the feedback, it's quite useful and it crystallizes some of the expected behavior for Boost authors. Here's a summary of what I got away from the answers:
1. Non-breaking changes can be done without restriction. 2. Small breaking changes can be made, but users should be given notice a few releases before the change is published. 3. For large breaking changes WITH a migration path from before-the-change to after-the-change (e.g. filesystem v2 -> v3), the change should be made by providing the functionality in a separate directory/namespace, and users should be given a few releases to move over. The before-the-change functionality can be removed after some time. 4. For large breaking changes WITHOUT a migration path (e.g. spirit 2 -> 3), the change should be made in a separate directory/namespace, and the before-the-change state should be preserved (because there's no migration path). 5. If a large change falling into categories (3) or (4) is equivalent to a redesign or rewrite of the library, this should be treated as a new library and a formal review (or at least a mini review) is encouraged.
Please correct me if I got something wrong. Would it be useful to document this officially somewhere on the Boost website? Is it desirable for Boost to adopt some kind of "official stance" on this matter (for now none of this is normative)? I can submit a PR to add the documentation if I only know what module I must submit it to.
As far as Hana is concerned, I think the logical thing for me to do is to proceed by way of small breaking changes with a deprecation period, at least for the time being.
I think, this is ok, but only as long as the affected functionality of the library will be still usable in C++14, i.e. C++17 features are completely optional.
Hello Louis and everyone,
On 4. Dec 2017, at 04:10, Louis Dionne via Boost <boost@lists.boost.org> wrote:
Would it be useful to document this officially somewhere on the Boost website? Is it desirable for Boost to adopt some kind of "official stance" on this matter (for now none of this is normative)? I can submit a PR to add the documentation if I only know what module I must submit it to.
I just want to second this. In case there is no consensus on establishing strict rules (for me personally the points 1-5 seem uncontroversial, might as well be rules), even guidelines are useful. A section in the Boost documentation for developers like "Best practice for breaking changes" would be helpful for everyone, even people outside Boost. Sometimes it helps in an argument to point to authority: "Look, what I propose for our company is in line with the best practices documented on the Boost page". Perhaps this is even worth a section in the CppCoreGuidelines. They have a section on "Modernizing code", so it is not out-of-scope: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md... Best regards, Hans
On Mon, Dec 4, 2017 at 2:37 AM, Hans Dembinski via Boost < boost@lists.boost.org> wrote:
Hello Louis and everyone,
On 4. Dec 2017, at 04:10, Louis Dionne via Boost <boost@lists.boost.org> wrote:
Would it be useful to document this officially somewhere on the Boost website? Is it desirable for Boost to adopt some kind of "official stance" on this matter (for now none of this is normative)? I can submit a PR to add the documentation if I only know what module I must submit it to.
I just want to second this. In case there is no consensus on establishing strict rules (for me personally the points 1-5 seem uncontroversial, might as well be rules), even guidelines are useful. A section in the Boost documentation for developers like "Best practice for breaking changes" would be helpful for everyone, even people outside Boost. Sometimes it helps in an argument to point to authority: "Look, what I propose for our company is in line with the best practices documented on the Boost page".
Perhaps this is even worth a section in the CppCoreGuidelines. They have a section on "Modernizing code", so it is not out-of-scope: https://github.com/isocpp/CppCoreGuidelines/blob/master/ CppCoreGuidelines.md#S-libraries
Best regards, Hans
+1 Seems sufficiently clear and non-controversial that this should simply be documented and followed as process (or at least guidelines). Plus, it nicely summarizes the thread for posterity, which would otherwise cause this thread to be repeated each 24 months. --charley
participants (18)
-
Andrey Semashev -
Boris Schäling -
charleyb123 . -
Daniel James -
degski -
Edward Diener -
Hans Dembinski -
Larry Evans -
Louis Dionne -
Niall Douglas -
Olaf van der Spek -
Paul A. Bristow -
Peter Dimov -
Rene Rivera -
Richard Hodges -
Robert Ramey -
Roger Orr -
Vicente J. Botet Escriba