Re: [boost] [AFIO] Review (or lack of it)

Subject: Re: [boost] [AFIO] Review (or lack of it)
From: Jeremy Maitin-Shepard (jeremy_at_[hidden])
Date: 2015-08-29 01:52:46

Niall Douglas <s_sourceforge <at> nedprod.com> writes:

> 
> On 28 Aug 2015 at 7:56, Jeremy Maitin-Shepard wrote:
> 
> > > > c) There are older versions in there. There is 1.3 and 1.4 at least (are
> > > > there more?). Please choose one. Go for it.
> > > 
> > > AFIO provides strong ABI and API evolution guarantees. It guarantees 
> > > that if you compile and link to v2 of the ABI, your code will 
> > > continue to compile and link no matter what changes next in AFIO.
> > 
> > It seems what you are trying to do is provide a demonstration of the way
> > backwards compatibility will work for future versions of AFIO, when it would
> > actually be useful, and also perhaps to provide an example of a good design
> > for supporting backwards compatibility in C++ libraries.  While this is
> > interesting, perhaps it would be better to do this as an example separate
> > from AFIO, so that AFIO can remain as small and simple as possible.
> 
> The documentation and tutorials explain - fairly tersely it is true - 
> how to pin your code to specific ABI versions or to always choose the 
> latest. The examples you ask for are littered throughout the 
> documentation. There is even a FAQ item with extra detail for the 
> curious.
> 
> It may well be because it's so lacking in obvious impact to end user 
> code you don't realise it all already works and you get it for free.

I understand that it is already supported, and I agree that it is great to
be able to pin to the current version (V2) and have assurances that it will
work, and this will also be useful once there is a V3.  It is just the
actual support for V1 that doesn't seem to serve any purpose, since my
understanding is that there aren't any users of it.  Please correct me if
I'm wrong.

I see that it is just a submodule reference within the repository, which
nicely separates the code, though presumably in the default case this will
result in users downloading/storing more data.

I do very much appreciate the principle of what you are trying to do, as far
as maintaining strict API/ABI versioning and clearly documenting changes
made between versions.  Indeed, this is something unfortunately lacking in
other libraries.  However, I think you picked too early a starting point for
maintaining this strict versioning, assuming my understanding that there
aren't any users of the pre-review versions is correct.

Therefore I suggest that the references to pre-review versions of AFIO
throughout the documentation should be removed, as they only add complexity
to the documentation without providing any value to actual users.  You could
still keep a history of the development of the library in a separate
document linked from the end of the table of the contents or something, but
this information should not be integrated prominently throughout the
documentation.

For changes made after the library has users, doing it the way you have been
doing clearly makes sense. 

> 
> > One comment on this design: it seems that different version of AFIO will
> > function as completely independent libraries, that can each be used
> > independently.  While this is certainly much better than what most C++
> > libraries provide, there is still the potential for AFIO version
> > incompatibilities: one piece of code (A) may rely on version X of AFIO but
> > also needs to interoperate (via AFIO types) with another piece of code (B)
> > that formerly relied on AFIO version X, but upgraded to AFIO version X+1. 
> > Ideally the backwards/forwards compatibility would be finer-grained, so that
> > this interoperability might be possible, but of course that tends to
> > severely constrain the types of changes you can make.
> 
> You may not be aware you can also build AFIO using any choice of 
> dependencies, so v1.40 has eight different potential configurations, 
> all of which are incompatible and will not work together. This is 
> unavoidable, because the dependencies do not work together e.g. 
> std::future does not work with boost::future.
> 
> All eight configurations will however coexist in the same translation 
> unit. The exact same thing goes for previous versions of AFIO, so v1 
> in its eight configurations will coexist with v2 in its eight 
> configurations. I haven't tested 16 copies of differently configured 
> AFIO in the same translation unit, but I do regularly test two copies 
> built with incompatible dependencies and that works very well.

I have been following the development of AFIO and your announcements
regarding APIbind with much interest, so I was generally aware of these
capabilities, although not the specific number of configurations.

I very much like that AFIO can interoperate with either different library
variants, but making the API and ABI depend on so many different
configuration choices has its own drawbacks.  Is there a way, for instance,
to make the library simultaneously interoperate with both filesystem TS
paths and boost filesystem paths?  Similarly for Boost future vs. C++11
std::future.