Vote in this topic: OCaml.org package latest version permalink URL

There’s two options for the upcoming permalink-to-the-latest-version-of-package-documentation URLs on OCaml.org:

(1) https://ocaml.org/p/ocamlformat/doc/[..]
vs
(2) https://ocaml.org/p/ocamlformat/latest/doc/[..]

Versioned URLs https://ocaml.org/p/ocamlformat/0.24.1/doc/[..] to refer to the documentation of a specific package version exist (now and in the future).

In option (1) it would be not advisable to name a version of your package "doc", since the documentation of the latest version of your package would have a URL conflict with the version "doc".

Option (2) is more explicit, more robust in terms of what version names for packages are admissible. However, it is longer.

Cast a vote by liking one of the posts right below this one. Feel free to discuss, as this is most likely the last opportunity to do so on this topic for a very long time. :slight_smile:

Like this post to vote for URLs like (1) https://ocaml.org/p/ocamlformat/doc/[…]

1 Like

Like this post to vote for URLs like (2) https://ocaml.org/p/ocamlformat/latest/doc/[…]

39 Likes

It’s extremely hard to find, but for future reference you can create “proper” polls in Discourse when creating a new topic. See screenshot…

3 Likes

Thank you very much! Indeed, I didn’t know. :see_no_evil: That is actually a great feature - why does Discourse hide it so well? :laughing: But any case, I’m glad to be the village idiot here, as long as I can help move things forward. In the future I will definitely make a real poll!

4 Likes

… definitely a plot to get a lot of likes :slight_smile:

8 Likes

A highly successful one, hehe.

But no, seriously, getting a sentiment from the community does help to justify the outcome of decisions that so easily trigger bikeshedding over irrelevant details. So thanks everyone for unblocking this in a very practical manner!

2 Likes

Can we also consider a query? E.g. https://ocaml.org/p/ocamlformat/doc/?v=latest (default to latest). Making the version of the resource part of the path itself, seems somewhat ‘un-RESTful’, if you take my meaning. A query also has the advantage that we can offer a simple drop-down to select the version (and it would just need a normal HTML form with a GET method, no JavaScript needed).

2 Likes

This implies that we would also have

https://ocaml.org/p/ocamlformat/doc/Parser_extended/Docstrings/WithMenhir/index.html?v=latest

instead of

https://ocaml.org/p/ocamlformat/latest/doc/Parser_extended/Docstrings/WithMenhir/index.html

which, while technically feasible, I don’t think is very obvious. That we could navigate via a HTML form GET request is true. Nowadays, the more common way to navigate between similar pages is to render HTML links formatted by CSS.

what some doc sites do is that they assign /package/doc/... to the latest version and /package-1.2.3/doc/... to the specified version. (notice the hyphen, or we can use a dot like in opam, versus a slash which would create ambiguity)

2 Likes

Looking at opam/opamPackage.ml at 5305e159d34ccc0b9fecbaa59727ac36e75f9223 · ocaml/opam · GitHub, I can confirm that the dot is a valid option, since opam will interpret anything after the first dot as the version.

So that would be /p/{PACKAGE_NAME}.{VERSION}/ and /p/{PACKAGE_NAME}/. :thinking: Tbh, I am tempted.

However, we have a patch almost ready to land with /p/{PACKAGE_NAME}/{VERSION}/ and /p/{PACKAGE_NAME}/latest, and I think, realistically, the best way forward in terms of resources is to go ahead with that.

I interpret the current votes as the fact that people overwhelmingly prefer regularity/predictability/discoverability of the URL scheme, even at the cost of longer URLs. So I don’t think that the proposal of @hyphenrf goes in the direction of the expressed crowd preference.

2 Likes

The proposal, rather an observation really, is more motivated with familiarity (opam already uses the name.version notation).
The ambiguity of the slash was referencing the unpopular option of this poll.
The benefit is urls as short as what we currently have, but without the ambiguity.