[Caml-list] Versioned deprecations?

[Caml-list] Versioned deprecations?

[Petter A. Urkedal]

On 21 June 2016 at 17:48, Gabriel Scherer <gabriel.scherer@gmail.com> wrote:
> (3) As Daniel pointed out, we need a better understanding of how to make
> code written using new stdlib functions compatible with older OCaml
> versions. So far we've used ad-hoc solutions on each situation, and it was
> barely manageable despite the small number of instances. (Bytes: in findlib;
> opaque_identity: clever hack; String ascii functions: no solution).

I guess the issue with the ASCII string functions is similar to one I
hit myself.  The introduction of `[@@deprecated]` helps a lot in
evolving interfaces, but there is the one annoying case when one wants
to give the identifier a new incompatible definition right away.  The
option seems to be to first rename, leaving a deprecated alias, then
wait for code to adapt before reusing it.  If the new definition is
introduced before, it needs to be under a temporary name, leaving
another deprecation.

This made me think of versioned identifiers as a possible way to
mitigate the issue.  The library interface would read e.g.

    val find : key -> 'a t -> 'a [@@obsolete "2.0.0"]
    val find : key -> 'a t -> 'a option

and tag the definition similarly.  The client code would announce
against which version of the library it was written.  At the point of
reference, the ppx or compiler would substitute latest versioned
identifier succeeding the announced version, or fall back to the
unversioned definition.  A purely syntactic transformation, though the
transformer must inspect the full signature of the module containing
the unversioned identifier.

The compiler issues a warning whenever an obsolete identifier is used.
What version of a library the client code requests is less important,
as long as no obsolete identifiers are chosen.  (That is just saying
that the user of a library shouldn't need to bother about updating
version requests before a warning occurs.)

There is a notable limitation of this solution, namely that when a
versioned deprecation occurs in a signature which types a functor
argument, the effect is opposite of what we want:  The client code
would be responsible for filling in the obsolete definitions.  Though,
solving this case seems to require a substantial changes to the module
system.