Policy for breaking changes

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
31 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Policy for breaking changes

Boost - Dev mailing list
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


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Policy for breaking changes

Boost - Dev mailing list
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



_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Policy for breaking changes

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
> 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/


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Policy for breaking changes

Boost - Dev mailing list
On Sat, Dec 2, 2017 at 6:33 PM, Niall Douglas via Boost <
[hidden email]> 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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Policy for breaking changes

Boost - Dev mailing list
Le 03/12/2017 à 03:37, Rene Rivera via Boost a écrit :
> On Sat, Dec 2, 2017 at 6:33 PM, Niall Douglas via Boost <
> [hidden email]> wrote:
>
>>> I'm looking forward to hearing other people's thoughts on the matter.
>> Boost.Hana2
>>
> That was a joke, right?
>
>
Why?


Vicente


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Policy for breaking changes

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Policy for breaking changes

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On Sat, Dec 2, 2017 at 10:52 PM, Edward Diener via Boost
<[hidden email]> 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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Policy for breaking changes

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
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




_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Policy for breaking changes

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
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.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Policy for breaking changes

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 03/12/2017 02:37, Rene Rivera via Boost wrote:
> On Sat, Dec 2, 2017 at 6:33 PM, Niall Douglas via Boost <
> [hidden email]> 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/


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Policy for breaking changes

Boost - Dev mailing list
On Sun, Dec 3, 2017 at 6:07 AM, Niall Douglas via Boost <
[hidden email]> 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 <
> > [hidden email]> 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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Policy for breaking changes

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
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


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Policy for breaking changes

Boost - Dev mailing list
On Sun, Dec 3, 2017 at 9:51 AM, Robert Ramey via Boost <
[hidden email]> 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
>.


--
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Policy for breaking changes

Boost - Dev mailing list
On 12/03/17 20:13, Rene Rivera via Boost wrote:

> On Sun, Dec 3, 2017 at 9:51 AM, Robert Ramey via Boost <
> [hidden email]> 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.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Policy for breaking changes

Boost - Dev mailing list
On Sun, Dec 3, 2017 at 12:36 PM, Andrey Semashev via Boost <
[hidden email]> 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 <
>> [hidden email]> 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.. <
>> <a href="https://bintray.com/bincrafters/public-conan/Boost.Hana%">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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Policy for breaking changes

Boost - Dev mailing list
On 3 December 2017 at 21:00, Rene Rivera via Boost
<[hidden email]> 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.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Policy for breaking changes

Boost - Dev mailing list
On Sun, Dec 3, 2017 at 2:42 PM, Daniel James via Boost <
[hidden email]> wrote:

> On 3 December 2017 at 21:00, Rene Rivera via Boost
> <[hidden email]> 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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Policy for breaking changes

Boost - Dev mailing list
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 <
> [hidden email]> wrote:
>
>> On 3 December 2017 at 21:00, Rene Rivera via Boost
>> <[hidden email]> 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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

[SPAM] Re: Policy for breaking changes

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

[SPAM] Re: Policy for breaking changes

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list

> 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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
12