Niall Douglas
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.