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.
Thank you very much! Indeed, I didn’t know. That is actually a great feature - why does Discourse hide it so well? 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!
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!
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).
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)
So that would be /p/{PACKAGE_NAME}.{VERSION}/ and /p/{PACKAGE_NAME}/. 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.
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.