confused by the ocaml5 images on Docker Hub

[gasche]

I just looked at a CI run for a CI script using alpine-3.15-ocaml-5.0, and I found it surprising.

This ocaml-5.0 image is not actually using a 5.0 release, but it seems to use the 5.0 maintenance branch. Relevant command:

RUN /bin/sh -c opam switch create 5.0 --packages=ocaml-variants.5.0.0+trunk # buildkit

I expected to get the 5.0.0 release instead (more precisely, from the name "5.0", the latest 5.0.x release, which currently is 5.0.0). In fact it looks like alpine-3.17-ocaml-5.0 uses 5.0.0, as well as alpine-ocaml-5.0 which I assume points to the latest alpine--ocaml-5.0 image.

Questions:

• There is a naming convention for opam switches to tell if it is pointing at a trunk branch or at an actual release. Why don't docker image names follow this convention as well? How can users tell whether they get a stable switch or not? (Correct me if I'm wrong, but I assume that +trunk switches install the latest commit of the development-or-maintenance branch after each repo+switch update, which sounds like not the right default for most projects using OCaml CI.)
• Is the image alpine-3.15-ocaml-5.0 never going to be updated and forever point to 5.0.0+trunk, or is it an oversight that alpine-3.17 uses the release but alpine-3.15 was not updated? (Both policies would make sense to me.)
• In the actual run of the CI image that I observed yesterday, the output of ocamlc --version was 5.0.0+dev10-2022-11-25. This is not the result one would expect from a compiler using ocaml-5.0.0+trunk -- at least on the actual upstream repository the current version output is 5.0.1+dev0-2022-12-15). This makes sense if this image was produced a year ago and is not intended to be updated. But then: how can I tell which version of OCaml (ideally, for non-release configurations: which git commit) a specific CI image is doing? Is this information available elsewhere, or is the easiest way to download and load the image and somehow inspect it? (Bonus points if you know how to get the git commit from the installed switch data.)
• There are also some -5.00 images, they seem to come from an older naming convention? (At first I assumed that maybe those were 5.0.0 images as opposed to some sort of rolling-5.0-release imaages.)

Is there some documentation somewhere of the expectations and best practices with using ocaml/opam CI images?

[dra27]

I can't remember how you get it from the command line, but the information in the Hub at https://hub.docker.com/layers/ocaml/opam/alpine-3.15-ocaml-5.0/images/sha256-c30eb992e95bced3e82ef1ec7e8fa46f9226f7628b848f98b0d485b688112578?context=explore reveals that image was written on Nov 26 last year, before the release of OCaml 5.0.0. The images track the +trunk package up to the first release when they switch to ocaml-base-compiler - at present, therefore, the 5.1.0 tags track the OCaml trunk branch, this will switch to tracking the OCaml 5.1 branch when that's created and then it'll switch to the 5.1.0 tag once it's released.

See also #57 for tracking what we should do with old distributions.

The metadata for keeping up with all this is in ocurrent/ocaml-version and ocurrent/ocaml-dockerfile which is what both the base image builder and ocaml-ci use to keep track both of what images should be available in the hub, and which versions of OCaml they'll contain.

[gasche]

Do images ever get rebuilt after they are published for the first time, or is the intention that they remain frozen forever?

I'm a bit nervous about the idea that it is so easy for users to use an image that does not correspond to an upstream release, without any clear signalling. Right now, a search for ocaml-5.0 suggests 97 possible images, 34 of which usee the actual 5.0 release, the other 63 have a weirdly outdated development versions.

(In contrast, as of course you know, the opam repository uses +trunk for maintenance versions, with a "beta" constraint to hide not-released-yet versions by default.)

In case it can help, here is the sort of organization that I would have expected -- as someone who knows very little about Docker, nothing about ocurrent etc. I am not saying that the docker images should move to this, but I don't understand the reasons for the current state and pointing out issues in my mockup alternative could be a way to explain the existing choices.

• Have images called ${distribution}-ocaml-5.0+trunk (I would find +dev more natural but opam uses +trunk) for development versions.
• Those +trunk images get rebuilt daily (or whatever works) to always point to the "current" development version when you run them.
• release images called ${distribution}-ocaml-5.0 on the first 5.0 release, that get rebuilt to point to the latest 5.0.x release

Users would use ocaml-${released-version} images to test against a given version (or just install several switches on top of a given image and use _opam caching), and ocaml-${version}+trunk in the rare situations (for most projects) where they want to check compatibility against an upcoming release.

(I was going to say that this gives the property that the ocaml part of image names coincides with switch names, but in fact we don't have "5.0 switches that point to the latest 5.0.x release"; I would like to have them!)

[avsm]

@gasche wrote:

(I was going to say that this gives the property that the ocaml part of image names coincides with switch names, but in fact we don't have "5.0 switches that point to the latest 5.0.x release"; I would like to have them!)

This is the key missing name. If we had this, then all of your other points would be easier, since the images currently track the release branch and not the release (deliberately, as their prime purpose is CI, and a very specific release can be built from within the image if desired).

[gasche]

Thanks for the feedback, I will consider opening an issue on opam-repository to discuss "last-patchset switches".
(I thought of contributing those directly in the past, but then I realized that there were design questions to discuss and solve.)

deliberately, as their prime purpose is CI

I don't understand why we are deliberately using moving-target switches for the purpose of CI. Can you explain?

Maybe this is about distinguishing two types of CI:

1. Some platform tools want to follow development (or maintenance) versions of upstream branches to ensure that they are working correctly at release time, and help catch bugs in upstream changes. Those are interested in branch-following CI images.
2. General OCaml developers that are reusing the CI images on ocaml/opam (as far as I know this is the recommended practice) probably do not want a moving-target image, right? I would expect that they want stability, using something expected to be used, and if (unlikely) there is an issue related to the OCaml compiler distribution they need to clearly know which version they are using for an upstream report.

Even for use-case (1), if the intention is to have CI images that track the development of the upstream branch to test compatibility / detect issues, then the CI images should be rebuilt regularly, which is not what is happening here I think?

[gasche]

and a very specific release can be built from within the image if desired

Sure, but my understanding was that those images are meant to save people the trouble and time of installing their own switches, the image comes with a switch pre-built. This seems to be how people use them in the wild. If the intent were to encourage people to build their switches, we should advertise an image with opam installed but no preinstalled switch, right?

[gasche]

I created an upstream issue on opam-repository to discuss "latest patchset release" switch names.

ocaml/opam-repository#22966

I originally thought that they should be named 5.0, but actually I think that 5.0.latest may be a better name, and could also be used in image names.

[avsm]

I don't understand why we are deliberately using moving-target switches for the purpose of CI. Can you explain?

With Docker, if you want a particular reproducible hash, then you query the image tag for the sha256 id and use that, resulting in a pinned image that wont change.

But if you just want to test with 'the latest 4.12', then the current tag gives you that and is resolved to a concrete sha256 hash at the point you pull it.

[avsm]

On naming, I think a reasonable convention (which is currently used) is that 5.0 or 4.12 represent the latest version (that is, they track the 5.0 or 4.12 branch in OCaml git). And something like 5.0.0 or 4.12.1 represent a tag in Git, and are not moving.

Or to put it another way, it's good to map existing git branches and tag names to the corresponding image names.

[gasche]

My problem with the current status is that I don't think users realize, when they see an image called "ocaml-5.0", that they may in fact be using some random in-development state coming from before the 5.0 release, in an unknown state of software quality. I find this mildly worrying. I guess I don't agree with this design choice. I think it should be hard for users to use an image that does not correspond to any OCaml release, they should be sure that this is what they want.

I also don't know of a way to actually tell from the image which git commit this in-development state corresponds to.

it's good to map existing git branches and tag names to the corresponding image names.

At the time of writing there are 54 images with ocaml-5.1 in their name, yet no 5.1 branch exists in the upstream OCaml repository.

[dra27]

There is possibly a slight issue with encoding the “latest” in the version rather than the name. I’m on my phone, which makes checking the Debian version comparison function opam uses tricky, but I have a feeling that 5.0.latest is less than 5.0.1. Assuming I’ve remembered that correctly, another option could be to have an ocaml-latest package - so ocaml-latest.5.0 as a switch base / invariant is always installs the latest point release… it’s not brilliant UX for the user (because it’s not very discoverable), but it would be fine for a CI image.

[gasche]

ocaml-5.0+latest could also work I guess.

[dra27]

@gasche - what caused you to select alpine-3.15? alpine-ocaml-5.0 is always the latest version of alpine on the latest release of 5.0… you only landed on a development release through selecting on old alpine release? The way those tags are setup is specified on https://hub.docker.com/r/ocaml/opam?

[gasche]

Actually someone else selected alpine-3.15-ocaml-5.0, but I recommended moving to alpine-ocaml-5.0 when I noticed the problem indeed. I don't know how alpine-3.15 was selected in the first place.

Thanks for the pointer to the documentation, which I had somehow missed. I think that I only ever land on https://hub.docker.com/r/ocaml/opam/tags, possibly after googling for a particular image name and then trying to "go up" in the hub hierarchy.

The documentation currently says:

All other tags are aliases to the latest version of a distribution and/or the OCaml compiler. For example if the latest Debian is version 11 and the latest OCaml is 4.13 then ocaml/opam:debian is an alias of ocaml/opam:debian-11-ocaml-4.13. The OCaml version will always point to the latest patch version, so 4.11 will be 4.11.X for the greatest X that is released. There are also some alternate OCaml configurations such as with flambda enabled or with frame pointers enabled.

This sounds very reasonable to me, but it is also different from what I observe in practice.

[avsm]

With respect to older distributions and out of date tags, that needs to be fixed by pushing 'deprecated' containers to those tags: see ocaml/infrastructure#7 and #57. We shouldn't let the tail wag the dog and change our naming scheme (perfectly good) because of an incomplete image builder (easily fixed, if someone could get around to it).