Introduce a versioned API for Alcotest V1

[craigfe]

This is the first real step towards #294: introducing a V1 namespace with a stronger stability guarantee. The Alcotest.V1 module is simply an alias of the current Alcotest API, enabling users to get fast migrations to future major releases by aliasing it:

module Alcotest = Alcotest.V1

[hannesm]

I am really not convinced of this approach (and indeed, some other libraries in the mirage organisation adapted such a behaviour already). From a zoomed out perspective, the packaging system (opam) is responsible for versioning. With an alcotest move from 1.x to 2.y, since it is a major version bump, the API may be revised, and clients have to adapt.

Now, introducing V1 modules in alcotest 2.y mean:

• we'll have to maintain them (or figure out: when will they be deprecated / disappear) -- leading to code smell/duplications,
• clients need to adapt to the new API anyways (at least by using the V1 modules) -> in opam, there will be lots of upper bounds and releases for alcotest 2.y compatibility.

So, what is the gain of such VZ modules? I really don't understand it. As a contributor and client of alcotest, I'm fine with adapting to a new API if a major version bump is done. For not actively maintained clients, they'll have an upper bound alcotest {< "2.0.0"} - which is fine, or is it not?

If you want smooth transitions from 1.x to 2.y, you should preserve the existing interface as is (no V1 prefix), and can still call it 1.x ;)

Some years back, we discussed how to deprecate functions, the resulting text is available at https://github.com/mirage/canopy-data/blob/master/Posts/Deprecating -- not sure whether this is still up to date.

After all, I'm wondering what the long-term plan for "versioned API for Alcotest V1" is, is there any plan to ever remove that module? I think the conduit API moved in that direction without any clear idea how to remove any of the code.

[craigfe]

I agree that this approach doesn't have any benefits for old projects that are not actively developed: they can just add an upper bound indefinitely (and this remains true when providing additional V1, V2 ... modules). It's also true that it doesn't solve the problem of needing to add these – at least temporarily – when releasing V2 to opam-repository.

The motivation for versioned submodules is that they make it feasible to gradually adopt new features in large – but still active – codebases for which a total migration is not worthwhile. New features can provide value to new users in terms of flexibility of test structuring / more expressive test predicates etc., but this isn't useful to test suites for which the user has already structured things exactly how Alcotest V1 requires.

(From my own work, I'm thinking of Tezos and Irmin, which still have many new tests added but for which there's no value to going back and spending hours changing the already-existing boilerplate to be a slightly different shape. Incidentally, Irmin also provides V1 modules for use in Tezos for the same reason.)

From a zoomed out perspective, the packaging system (opam) is responsible for versioning.

Versioning large changes with Opam alone forces users into all-or-nothing adoption in each of their repositories. This seems sensible to me when the large alters behaviour fundamentally or adds a lot of value to existing call-sites, but I think neither of these hold here:

• the current test DSL is tiny and should be fairly easy to provide compatibility for. (My current V2 draft implements the migration in < 100 lines of mostly types here.)
• the value added by new features will never justify a complete migration in a sufficiently-large codebase, so such users will just stick to Alcotest V1 forever (and I'd end up needing to maintain a V1 branch for these projects anyway).

All in all, I think the fact that Opam doesn't support installing multiple versions of the same package (unlike, e.g. npm's package aliases) means that it can never be the all-encompassing solution for versioning in large codebases.

Some years back, we discussed how to deprecate functions, the resulting text is available at https://github.com/mirage/canopy-data/blob/master/Posts/Deprecating -- not sure whether this is still up to date.

I like these guidelines as they apply to small API changes like individual function removals, under the assumption that all existing users will eventually want to migrate unconditionally to the "new way" across their entire dependency tree. However, API changes can be worthwhile / feasible for new users but not existing ones. (Another example of this is encoding formats in Irmin, which some users will inherently leak as part of their own API and so need an internal versioning scheme.)

After all, I'm wondering what the long-term plan for "versioned API for Alcotest V1" is, is there any plan to ever remove that module? I think the conduit API moved in that direction without any clear idea how to remove any of the code.

I suspect Alcotest V1 is simple enough to be maintained indefinitely, but it's also possible to do a deprecate / remove cycle several major versions down the line. The span of Va ... Vz modules supported by Alcotest main need reflect only what is worthwhile to maintain at the time. Viewed this way, the point of these submodules is to provide deprecated namespaces that don't get in the way of new APIs.

Hope that clarifies my justification; apologies for the length :-)