Documentation versions

[bvaughn]

This issue was originally reported by @shripadk via facebook/react/issues/2424

It would be great to have documentation for various versions of React similar to http://nodejs.org/docs/

Netlify already permanently caches deployments so we should be able to use it to link to older versions of the docs at specific times. The new website header also has a UI label for the current version that could easily be turned into a drop-down selector for toggling between past versions.

How would the drop-down menu work?

We could store a list of snapshot deployments (eg 16.0, 16.1, etc) in a JSON or YML config file in GitHub and the latest deployment of the docs site could use it to build the list of links to older versions of the docs.

Older versions of the site could make an HTTP request to load the list dynamically from eg reactjs.org/some/static/path/versions.json. This would enable older versions to be updated with links back to newer versions of the docs.

Why not build and deploy older versions of the docs?

One or two people have asked why not just build old versions of the docs now, with the newer site. My concerns with this would be:

• Gatsby's config and our view templates tie the markdown content and layout together in such a way that changes to either would make building older versions of the docs difficult (eg reorganizing our directory structure would require forking our Gatsby build process).
• It would complicate translation efforts via Crowdin.
• It would probably slow the build process down.

[bjrmatos]

it will be also cool to have a reference to the initial version that an API was introduced.

example (from node.js docs):

[bvaughn]

Agreed that could be a nice addition as well! 😄

[KyleAMathews]

An interesting option too would be to use git-worktree to checkout past branches to build older versions of the docs within Gatsby.

[KyleAMathews]

It'd slow things down builds somewhat but since the older stuff will be cached after the first build, it might be quite workable still.

[bvaughn]

What would be the benefit of building past branches like this vs just linking to snapshots in time?

It would give us the chance to improve old docs or fix bugs, but I'm not sure that's super important.

[KyleAMathews]

It just feels like an odd navigation scheme to link to an old version of the website instead of just linking to older docs. But agree it's far simpler and probably perfectly adequate.

[bvaughn]

We could always rebuild older versions of the site if necessary by stepping back through Git commits, but things like the error codes dependency between reactjs/reactjs.org and facebook/react will make building legacy versions difficult and not something I want to commit to doing/supporting all the time. Only if necessary. 😁

[KyleAMathews]

Oh, and just to make sure my point is clear — I just meant build out separate pages for different versions. So https://reactjs.org/docs/introducing-jsx.html but also https://reactjs.org/v15.6/docs/introducing-jsx.html, etc. Then you'd have a drop down in the docs that list older versions. So most of the site would stay the same but the docs would be versioned.

[bvaughn]

I think we'd have an even harder time doing that. The website source is pretty coupled with the content (eg the location of the markdown files, the nav YMLs, etc).

[jaredp]

Is it possible to see the netlify cached older versions of the docs site today, even if they're hard to link to?