What's the ocaml.org process for a new OCaml release? #819

gasche opened this Issue Aug 4, 2016 · 4 comments


None yet

3 participants

gasche commented Aug 4, 2016

Hi ocaml.org maintainers,

I feel that the questions I asked in the old email thread

[ocaml-infra] ocaml.org update on new OCaml version
September 14, 2015

have not been answered in a way clear enough to act upon. There will be the 4.04 release in a couple months (I guess), and I would like to do the right step to get ocaml.org up to date at the time of the release time, but for that I would need a clear checklist of what changes must be made when a new release occurs somewhere. (Bonus point if you can describe the steps both for a new major version and a new minor version.)

Chris00 commented Aug 4, 2016

See also #818

Chris00 commented Aug 4, 2016


  • Make sure it has an opam switch (this is used to automatically determine the latest version mentioned on the install page). [One could also use the content of site/releases if that sounds more sensible to you.]
  • Create a file in site/releases describing the release. The file should have the name <version>.md where <version> is the version in OPAM (this is important for the link on the install page to work).
  • Add an entry to site/releases/index.md.

So far, there is no real policy for minor releases that I know of. The OCaml release team can decide what they prefer. A simple way of proceeding is treating all releases on a equal basis: they all have their own page. Maybe the minor release X.Y.Z can point to X.Y.(Z-1) only describing the diff with it and be mentioned as such in site/releases. But other possibilities are equally valid (note though that it all minor versions X.Y.Z end up in the same file X.Y.md, then the above suggestion to use the content of site/releases will not work—but that's not what we do now anyway so you can choose that possibility).

Hopefully I didn't forget anything!

amirmc commented Aug 5, 2016


From the thread you link to:

Should we consider that updating the relevant ocaml.org pages is part of
the release process?

Yes, please!

On the last couple releases I have helped (as part of my Changelog-patting
process) Damien and Xavier come up with a short summary of the changes, to
craft an announce on caml.inria.fr. Should we do this for ocaml.org now?

Again, yes please! A short summary of the changes would be great and we can highlight it in the News section (just as the MOOC and OCaml 2016 are now). Christophe has done this for the 4.03 release page and #818 is about doing this on an ongoing basis.

One subtlety is that some updates only make sense after the corresponding
OPAM switch has been made available in the official repository. There is no
formalized synchronization between the release announcment and a switch,
but in practice a switch is released on the day of the release, and for
4.02.2 and 4.02.3 it was prepared by Damien directly (and merged in a few
hours by the opam-repository maintainers).

We could send a pull request for the website at the same time as the
compiler description, and wait for its integration to announce the release.

I don't think you need to wait for the merge to actually have happened to announce anything (unless there's a reason you think CI might fail). Submitting a PR should be enough and IMHO it's perfectly fine to say something like "... will be available in OPAM shortly." As you mention, the difference is only a few hours.

In addition, someone involved with the OCaml release process should be able to merge PRs for ocaml.org (so that they can update relevant pages).

amirmc commented Aug 5, 2016

So far, there is no real policy for minor releases that I know of. The OCaml release team can decide what they prefer.

When 4.02.0 was released there were problems noted, and we ended up doing the following on ocaml.org:

The above isn't formalised but it's what we ended up doing when 4.02.1 was released, and it seemed to work ok. IIRC part of the reason for not having a separate release notes page for each was because they'd largely be duplicated.

Unless there are other opinions, I think it's ok to stick with the above steps. The only thing I'd change is the note on the most recent release page to mention that previous versions are still available via OPAM (rather than linking to caml.inria.fr).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment