Maturity rating

[rrthomas]

We should add a maturity rating so we can introduce experimental APIs and change them without upset.

On the whole this should not affect direct wrapping of POSIX functions; and since most of luaposix is just that, it shouldn't have much effect.

Indeed, labelling something experimental may be a sign it should be spun out (e.g. pipeline).

[gvvaughan]

Do you mean programmatically marking experimental APIs, or "just" making note of such things in the release notes?

If programmatically, what's the user interface (as opposed to the API)?

[rrthomas]

I mean marking in the docstring/programmatically, just as we do with obsole{scent,ete} APIs.

[gvvaughan]

+1

I'm beginning to lean towards spinning the whole gradual typing machinery out into a separate rock now, where the various half-baked versions I have can be glommed together, and (optionally) depended on when necessary.

Perhaps all the debug enhancements I've written this last year, plus experimental and deprecated annotations could live here too?

[rrthomas]

I would rather make type-checking mandatory. luaposix is mostly I/O and/or system calls, i.e. the overhead will not be significant.

[gvvaughan]

For luaposix, I can see the argument (not sure whether I'm sold on it yet though). But, ultimately, I'd like to publish the gradual typing calls to third-party Lua modules, where it's not so cut and dried.

By spinning it out, at the very least it keeps a proper separation of concerns and makes for tidier luaposix sources, as well as forcing the API to move towards sanity.

[gvvaughan]

You'll notice that I recently separated std.maturity out for the Lua side in lua-stdlib/lua-stdlib@1701cf3 - I'm not sure whether that will be enough to satisfy luaposix's requirements, but I'll experiment with it a little, and maybe ask for you to create a 'stdlib/maturity' project for me to hang it off if things work out?

[rrthomas]

I'd be inclined to mark only three things: 1) bindings whose details change for some reason, 2) (non-maturity-related) anything non-POSIX that gets in [FOR A REALLY GOOD REASON!] and 3) bindings that go away because the underlying POSIX API does (that's a different sort of obsolescence, I think).

I think even more now that anything non-POSIX should go in its own library. (A good example is my pipeline code, sigh.)

[gvvaughan]

Agreed. And we're fast closing in on the 1-year anniversary of v33.0.0, which will make room to eject quite a lot of the backwards compatibility cruft supporting changes up to that point.

It sure would be nice to ship an ultra-slim luaposix v34.0.0 in early 2016...