Julia: Changes to docs deployment conventions

[mortenpi]

Currently Documenter deploys documentation into various subdirectories on gh-pages, each of which shows up in the version selector and corresponds do a different URL (https://docs.julialang.org/en/$dir). The naming logic is as follows:

• Commits on the master branch get deployed to latest/

• Version tags (i.e. vX.Y.Z) get deployed to stable/, release-X.Y/, vX.Y.Z/

  Specifically: (1) every tag/patch version gets its own directory, (2) the latest release of every minor version is available in release-X.Y, (3) the latest tagged release is available under stable/.

In #documentation on Slack there were two suggestions to change this a bit that gathered some support:

• Removal of the release-x.y directories/URLs. (JuliaDocs/Documenter.jl#706)

  You can already access the docs for each individual version, so having release-x.y directories/URLs seems redundant.

  For Base docs this would mean deleting release-0.6/ and we wouldn't have release-0.7/ or release-1.0/ in the future. release-0.3/4/5 should be kept, as there are no per-tag docs for those, but should probably be renamed.

• Renaming latest to something else (JuliaDocs/Documenter.jl#337). Quoting @fredrikekre here:

  What would people think about changing the naming of latest docs to something like master/development/unstable? latest is just too nice of a word, and it feels like latest docs would be the docs for the latest release.

  I.e. the URL for master docs would change to e.g. https://docs.julialang.org/en/master/ as opposed to the current https://docs.julialang.org/en/latest/ It should be possible to set up redirects for latest/ to keep existings links alive.

  The name could use a bit of bikeshedding I guess -- I can think of devel/ or dev/ in addition to those already suggested.

My view is that Documenter's defaults should generally follow Base, to encourage packages to follow the conventions here. So I'd say we should make the changes in Documenter only if we have an agreement here to change the conventions.

[StefanKarpinski]

What about X.Y-DEV for the development version and X.Y for each major/minor release which should take you to the docs for the most recent X.Y.Z release. Ideally these should be sorted in correct version sort order.

[fredrikekre]

What about X.Y-DEV for the development version

That would work for julia base, but how should we do this for packages? For example, if the latest release is X.Y.Z, should we assume that the next one will be X.(Y+1) and display it as X.(Y+1)-DEV? Another issue here is that the latest doc version might not correspond to the latest actual release of the package. For packages without releases, how should we display it then? 0.1-DEV?

X.Y for each major/minor release which should take you to the docs for the most recent X.Y.Z release

I like the idea of having only 0.6 docs instead of 0.6.0, 0.6.1 and 0.6.2 docs since those should only be bugfix-releases. It has been suggested though that it can be useful to have dedicated pre-release docs for users to consult when testing out a new release. Should we have separate docs for each tag, but merge non-pre-releases? Such that when tagging 0.7-0-rc1 or w/e we would have that as a doc version, but if we released 0.6.3 we would just overwrite the 0.6.2 docs in the 0.6 directory?

[StefanKarpinski]

Having a dev name for what's on master seems fine (maybe just call it master?). I do think that releasing 0.6.3 should overwrite the 0.6 docs—there should not be breaking changes in patch releases so that should only contain fixes and improvements to the documentation and listing every point release is just noise. Maybe the simplest way to do this is to include the full release version number but only keep one per minor release. In other words list 0.6.3 as 0.6.3 but when that gets added it replaces 0.6.2 instead of being in addition to 0.6.2. That solves the pre-release problem too since tagging 0.7.0-rc.1 will cause that to appear in the docs list as such but later when 0.7.0 is release that will replace it.

[fredrikekre]

Sounds good to me. We could just keep the other version on the branch though, just exclude them from the version selector, such that links will still work.

[StefanKarpinski]

such that links will still work.

OTOH it might be better for the links to point to the new version of the docs, assuming that point releases won't have major structural changes.

[mortenpi]

Trying to synthesize:

In order to have a complete record available, I would keep each version on gh-pages under their respective vx.y.z/ directory. However, they will be hidden from the version selector -- noise, as you said. Pre-releases would also get deployed into their respective directories (e.g. v0.7.0.-rc1/), but the version selector would only show the one with the highest version number.

The user facing URL would be vX.Y/ (e.g. https://docs.julialang.org/en/v0.6/...). We can actually achieve this with symlinks, with vX.Y/ pointing to the latest vX.Y.Z/, avoiding copying and making it clear to us what version vX.Y exactly is (if there's a problem with the docs).

What about once we get to major releases though? I am starting to feel that we should just have a single doc for each major one (e.g. https://docs.julialang.org/en/v1.x/...). If we do go for a single major version doc, the it would probably make sense to get rid of stable/. The canonical URL of the docs should be per major version, since docs will likely change quite a bit between major versions.

It might be good to have stable/ as a redirect, although the root https://docs.julialang.org/ already does that.

A couple of datapoints:

• Node seems to have a single URL per major versions (e.g. https://nodejs.org/dist/latest-v9.x/docs/api/). Their <link rel="canonical"> URL is https://nodejs.org/api/....
• Python is a bit confused but
  
  
  
  • From the main site the point to major version URLs (https://docs.python.org/2/, https://docs.python.org/3/)
  
  
  • Once in the docs, you can access some minor versions (e.g. https://docs.python.org/3.5/, https://docs.python.org/3.6/). But the <link rel="canonical"> URLs are the major version URLs.
  
  
  • They also make each individual patch release available (https://www.python.org/doc/versions/), but they don't clutter the version selector with it. However, the major/minor versions URLs look like symlinks to the release docs.
  
  
• Ruby seems to have per-patch version (e.g. https://ruby-doc.org/stdlib-2.5.0/), with a root URL redirecting to the latest version.
• Rust has rolling docs -- just a single unversioned doc as far as I can tell.

---

Bikeshedding latest/: I feel that master, while clear to everyone familiar with Julia development, might not be immediately obvious to a more general audience / users (e.g. people not that familiar with managing projects on Git or who are used to the dev branch workflow). Hence something that would be more explicit about it being the latest development version would be better in my opinion.

[fredrikekre]

Here is my proposal:

We remove the version selector and replace it with something like:

This is the docs for the latest release, for older versions, and in development version see [docs by version](link)

where link points to a page similar to https://www.python.org/doc/versions/

What does this solve?

• We don't need to choose which versions should be in a version selector (i.e. all, minor or major releases), the front page is always the latest release
• We don't need stable, which is IMO quite vague anyways.
• We don't have to come up with a better name for latest (it is hard to come up with a good one-word description that is not ambiguous) -- we just list it at the bottom of the version page and call it In development version of the docs which is very clear (https://www.python.org/doc/versions/#in-development-versions)
• We can keep the underlying structure with folders for all tags

[fredrikekre]

Me and @mortenpi have discussed this a bit more, and here is what I think we will do unless anyone disagrees:

• [x] Tag vX.Y.Z deploys to a vX.Y.Z folder (this already happens).
• [x] Symlink vX.Y to vX.Y.Z for latest Z (https://github.com/JuliaDocs/Documenter.jl/pull/813)
• [x] Symlink vX to vX.Y.Z for latest Y and Z (https://github.com/JuliaDocs/Documenter.jl/pull/813)
• [x] Put vX as the canonical url (#28792, #28821).
• [x] Remove stable docs (#28792, #28821).
• [x] Rename latest to dev (although this can be configured with a kwarg, so the Julia manual can easily have v1.6-dev and v2.0-dev when we branch) (https://github.com/JuliaDocs/Documenter.jl/pull/813)
• [x] Remove release-X.Y docs ( #28710).

The version selector will include the following, in order of appearance

1. vX.Y for all X and latest Y (that is, we will eventually have v1.5 and v2.1 or something in there)
2. v0.X for all X (?)
3. dev

[StefanKarpinski]

Sounds perfect.

[fredrikekre]

This is done :tada: .