Add compat module.

[toots]

This PR adds a new internal, non-public library. This library should provide a backward-compatible API so that all projects using camomile pre-2.0.0 API can use it if needed. We want to encourage user to migrate to the new API so the library is only provided as example and not as public package.

[Alizter]

I think that this is a good idea since there will necessarily be projects that will not update to camomile 2.0.0 and it will be up to package maintainers to keep comparability. Having a dedicated compat module is a much less invasive strategy than maintaining a series of patches.

[toots]

I think that this is a good idea since there will necessarily be projects that will not update to camomile 2.0.0 and it will be up to package maintainers to keep comparability. Having a dedicated compat module is a much less invasive strategy than maintaining a series of patches.

Just pushed an update that should make the compat update totally transparent. Just replace any use of the camomile package with camomile-compat and your code should compile with deprecation warnings.

Could you confirm? I'm ready to release this.

[Alizter]

I haven't been able to confirm this yet, but I will ASAP.

[Alizter]

So I was testing liquidsoap 2.1.4 and I get:

File "configure.mli", line 36, characters 30-68:
36 | module CamomileCharEncoding : CamomileLibrary.CharEncoding.Interface
                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Error: Unbound module CamomileLibrary

ah whoops nevermind. I just realised I need to patch camomile to be camomile-compat.

[toots]

So I was testing liquidsoap 2.1.4 and I get:

File "configure.mli", line 36, characters 30-68:
36 | module CamomileCharEncoding : CamomileLibrary.CharEncoding.Interface
                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Error: Unbound module CamomileLibrary

ah whoops nevermind. I just realised I need to patch camomile to be camomile-compat.

Yes, the diff is annoying but that's because our build system pre-dune is also annoying :-)

It's here: https://gist.github.com/toots/ca314c1829c729ff4384d3c500ef8f6b

[Alizter]

@toots Is there anything left for this?

[toots]

After some thinking, I'm a little hesitant to release a compat module actually.

My original thought was that, without a compat module, there is no way to build all the modules depending on the old camomile API.

However, this also comes at the same time as the new 5.0.0 OCaml compiler also had a new, incompatible API. In fact, the new Camomile release was developed because it wasn't compiling with OCaml 5.0.0.

In other words, all the projects currently broken because they do not support the new camomile API are, in fact, broken because they do not support the new compiler API.

For this reason, there doesn't seem to be a pressing need to provide a compat module from a usability perspective.

The argument against a compat module, on the other hand, is that, once it is provided, it will be carried for a while, kicking down the road the issue of fixing unrelated code that, eventually, needs to be updated.

So, I'd rather use the opportunity of the global OCaml 5.0.0 API breakage to rip the bandaid right now, leave the new API in place and provide good documentation on how to adapt to it.

This would include, I believe, the code for the compat module, which could be provided as an example but not in the official API.

[Alizter]

Very well, in that case we can turn the compat API here into a migration guide for people looking to port their libraries.

[toots]

Very well, in that case we can turn the compat API here into a migration guide for people looking to port their libraries.

Exactly! I'll push that shortly!

[toots]

@Alizter I added an entry in the README.md. What do you think of it?

[Alizter]

LGTM