Retiring opam2web in favor of ocaml.org

[sabine]

Hey everyone,

• https://ocaml.org/packages has feature-parity with https://opam.ocaml.org/packages
• the changelog at https://ocaml.org/changelog publishes the information that used to go in https://opam.ocaml.org/blog
• I have prepared a patch that moves the opam documentation to ocaml.org Move opam docs from opam.ocaml.org ocaml/ocaml.org#1367
• Changing the Markdown files in doc/pages to be amenable for use on OCaml.org ocaml/opam#5593
• serve the remaining posts from the Opam blog at ocaml.org without regression (i.e. on a dedicated page with an RSS Atom feed). Give Local Blogs a Page and RSS Feeds ocaml/ocaml.org#1459 (currently, the RSS feed does not include the Opam changelog - maybe it should?)
• After confirming that everything is fine on ocaml.org: Make opam2web serve only the package archive, the opam release key and the redirects to ocaml.org

NOTE: In the patch for ocaml.org that I almost have ready, I am not hosting the legacy documentation for opam 1.1 and 1.2. The legacy documentation still exists at https://github.com/ocaml/opam/tree/1.2/doc/pages and https://github.com/ocaml/opam/tree/1.1/doc/pages.

Please speak up if you see anything that prevents us from retiring the website at opam.ocaml.org.

NOTE 2: hosting the markdown files of the opam documentation on ocaml.org is a temporary measure: as soon as odoc can build manuals, we move the opam documentation into an opam package - so that the documentation pipeline will build the opam docs, and so that documentation for all existing and future versions of opam can be easily integrated into ocaml.org or other websites.

Alternatives to hosting opam docs on ocaml.org:

1. remove only the packages section from opam2web (however: shutting down the website entirely will place less burden on the ocaml.org infrastructure folks, allowing them to do more useful work!)
2. someone creates a simple, modern and maintainable website for opam (but again, you could be contributing to something more impactful that creates less maintenance burden)

[avsm]

Thanks for starting this off, @sabine! We won't be able to fully switch off opam.ocaml.org for some years, since it's the default URL from which opam packages are served (when you do opam init). There are also a number of external links that point to the existing site from the outside. What we could do is:

• generate a one-off set of redirects for existing URLs that redirect to the appropriate v3.ocaml.org urls (for example, the documentation and the blog posts and the history page).
• make opam2web output just that redirect map, and the existing package archives.
• opam.ocaml.org parses the redirect map, and is otherwise a static https site for the opam package archives.

[avsm]

It's also got the release key (#226) for opam. It's probably a good time to figure out if we want to centralise the key management a bit more (e.g., do we want to do this for compiler releases too?)

[sabine]

Thank you @asvm, I wasn't aware of the release key and will make sure to take care with the redirects. I now have a much better understanding what will be left here at opam2web. 👍

[rjbou]

Thanks @sabine & @avsm!
I want to add to the list that in the actual opam.ocaml.org there is also the packages cache opam.ocaml.org/cache.

On documentation, for the moment opam.ocaml.org show master's documentation. Would it be possible in ocaml.org to have several versions documentation, for example 2.0, 2.1, and master one before the move to odoc documentation? Otherwise, it is preferable to have last release documentation by default (even if it hides for some people the current one, but less people are concerned).

For the release keys, I have a plan to generate new ones properly (signed primary & sub keys), and to register them in key servers. Once done, there will be no more the public key stored in the website.

[rjbou]

Also,on moving opam documentation into opam package documentation, note that there is no opam package, it is opam-devel the package that builds opam binary. And it can be confusing for people looking for opam documentation.

[sabine]

Thank you @rjbou, taking care of the keys is super useful!

I'm adding the older versions of opam documentation to ocaml.org as well.

That the package is named opam-devel is perfectly fine. I think it's very likely that we will have a separate UI for platform tool manuals on ocaml.org. I wouldn't use the package documentation area that exists on ocaml.org because it bombards people with noise (search bar, package overview info) they don't need to see at the time they're learning about the platform tools - it's more useful to show them tutorials nearby the platform manuals in the Learn area.

Regarding the opam documentation:

• @christinerose is doing line editing on the documentation I moved to ocaml.org and I had to do a little bit of editing as well.
• can we make the opam documentation on ocaml/ocaml.org the primary source of truth until odoc can properly build the opam manual? When this is the case, we would move the opam docs off ocaml/ocaml.org and back into ocaml/opam's individual branches.

ETA: ok, I have a better idea for this:

1. ocaml.org hosts the docs for opam releases 1.2 and 2.1. We can drop the 1.1 docs, no?
2. I make a PR on opam's master branch where I replace the current markdown files with the ones after line-editing. Then, primary source of truth is still ocaml/opam, and when a new release is cut, we can add a snapshot of the the docs to ocaml.org - if that happens before we can generate them with the documentation pipeline.

ETA2: Unfortunately, we're losing the hosted man pages, unless we can find another place to host them. So I'll have to remove the links from the docs to them.