Re: Backward compatibility

Subject: Re: Backward compatibility
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2018-07-04 22:01:36

On 4 July 2018 at 18:04, Stefan Seefeld <stefan_at_[hidden]> wrote:
> On 2018-07-04 08:13 AM, Mateusz Loskot wrote:
>>
>> We're shaking off the Grand Merge, releasing
>> significant GIL update with Boost 1.68 and
>> soon we will be able to move forward (towards GIL 3?).
>>
>> I've already started removing lots of dependencies
>> from Boost itself, replacing them with C++11.
>> The one more challenging is removal of Boost.TypeTraits
>> and some bits of MPL [1].
>> This experience made me wonder how we should approach
>> significant changes in the API, structure of public headers, etc.
>> for backward compatibility.
>
>
> So far we were using the fact that GIL hasn't received updates in years as
> rationale for not caring much about backward compatibility.

Yes

> However, moving forward the hope is of course to (re-?)build a GIL user
> community, so we definitely should care for API compatibility.

That will be reasonable appraoch.

> It remains however to be
> defined what exactly that means (including to what degree we want to enforce
> compatibility, establish deprecation policies, etc.).

Indeed.

I think Boost.TypeTraits & MPL clean up [1] may be a useful exercise

[1] https://github.com/boostorg/gil/pull/107

> But since Boost itself doesn't provide any backward compatibility
> guarantees, I think it will be difficult to provide guarantees as long as we
> depend on Boost as much as we do now.

I still think we may want to familiarise ourselves with [2] as the
outcome of [3]

    "Large breaking changes that are equivalent to a redesign or
     rewrite of the library should be treated as a new library
     and a formal review (or at least a mini review) is encouraged."

Aa well as with alternative takes on compatibility like [4] suggested
by Peter Dimov.

[2] https://github.com/boostorg/website/pull/300/
[3] https://lists.boost.org/Archives/boost/2017/12/240108.php
[4] https://lists.boost.org/Archives/boost/2017/12/240117.php

> Thus, our priority should be to reduce our dependency on Boost as much as possible,
> at which point we are in a much better position to become backward compatible.

Yes, I agree and, as already explained, that is what I'm setting as my priority.

> As far as header structure is concerned, I think for the core library we
> should establish `boost/gil.hpp` as the only public header, so we are free
> to restructure anything inside boost/gil/ without concern for users.

This is a very useful guideline. I like it.

> Likewise, extension APIs should each have their own top-level header (e.g.
> `boost/gil/extension/io/png.hpp` for the PNG IO extension) as the public
> entry point, and anything else is implementation detail.

Yes.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net