[Caml-list] Determining compatibility for evolving programming interfaces

[Caml-list] Determining compatibility for evolving programming interfaces

[Markus Elfring]

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?

* Which kind of variations can be occasionally tolerated in interface descriptions?


I would appreciate your advices.

Regards,
Markus

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

[Malcolm Matalka]

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

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

[Fabrice Le Fessant]

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

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

[Yawar Amin]

[-- Attachment #1: Type: text/plain, Size: 850 bytes --]

In general this is very difficult, because of 'module type of' and
functors. Almost any change can be a breaking change. If we pretend that
those two don't exist then we can make a modest set of guarantees. See
https://inbox.ocaml.org/caml-list/71ff7d61-6899-9b05-4c01-3984d47698ca@cea.fr/t/#u
for
more on this.

Regards,

Yawar

On Sat, Jan 2, 2021 at 2:51 AM Markus Elfring <Markus.Elfring@web.de> wrote:

> 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?
>
> * Which kind of variations can be occasionally tolerated in interface
> descriptions?
>
>
> I would appreciate your advices.
>
> Regards,
> Markus
>

[-- Attachment #2: Type: text/html, Size: 1331 bytes --]