Re: [Caml-list] Determining compatibility for evolving programming interfaces

[Fabrice Le Fessant <fabrice.le_fessant@origin-labs.com>]

Hi,

   In a few libraries I have been involved recently in the
development, we decided to export the interface under a module `V1`,
with the principle that we shouldn't make incompatible changes to V1,
or switch to a new interface V2, keeping V1 as it was. Then, the user
can use `open Library.V1` to access the interface and have more
guarantees that it will not break too often in the future. As Malcom
wrote, we assume that some changes in the interface are ok without
changing the version, like adding an optional argument or a field in a
record, though it is possible for such changes to break other packages
(if the function is passed as an argument for example, or if
warn-error is enabled). For now, it is just an experiment, made also
possible by the fact that these libraries are "one-module" libraries,
and we will see in the future if it was a good idea or not.

--
Fabrice




On Mon, Jan 4, 2021 at 7:05 AM Malcolm Matalka <mmatalka@gmail.com> wrote:
>
>
> Markus Elfring <Markus.Elfring@web.de> writes:
>
> > Hello,
> >
> > OCaml is also an instance of a programming language where type inference belongs
> > to core functionality. The usage of various data types will evolve in several
> > programming interfaces.
> >
> > * How do you think about to check if API revisions are still
> > compatible there?
>
> IME, this is really up to the author and I don't know if there is a
> single correct answer.  Usually people define it as if, between
> versions, the function does the same thing given the same inputs.  The
> common question is: what about bug fixes?  Whether or not the fix is to
> document the bug fix because people depend on it or break it is up to
> the developer.
>
> >
> > * Which kind of variations can be occasionally tolerated in interface
> > descriptions?
>
> From a technical perspective, the following are safe:
>
> - Adding optional parameters
>
> - Supporting more polymorphic variant types.
>
> - Returning fewer polymorphic variant types.
>
> - Probably similar with objects but I don't have much experience with
>   objects.
>
> From a human perspective, I tend to be OK with breaking changes if the
> cause a compilation failure, that way the developer is forced to
> understand the change and update it.  If an interface is sufficiently
> changed, I might just make a new library (library2) that implements the
> change, especially if the core functionality is staying the same and I'm
> mostly changing the feel of the library.  That's also nice if you're
> comparing two implementations and want to have them side-by-side.
>
> I, personally, find semantic versioning to be not very useful because,
> at the end of the day, it requires humans to make decisions about if
> their changes fit into the various categories of change, and by our
> nature we don't like to increment the major version for some reason.
> I've come across numerous libraries in opam that break even compiling
> despite not changing the major.
>
> >
> >
> > I would appreciate your advices.
> >
> > Regards,
> > Markus