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?

[jaredp]

For anyone who comes across this issue trying to find old docs, for now, you can use the Wayback Machine https://web.archive.org/web/20170624111014/https://facebook.github.io/react/docs/state-and-lifecycle.html

[bvaughn]

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

Not in the way that I think you're asking. We weren't using Netlify until very recently.

[clemmy]

@bvaughn Is there any work currently being done on this? I can help out with this. 🙂

[bvaughn]

This issue is all yours, @clemmy 😄 Feel free to chat with me if you want to discuss ideas or anything.

I've added an "in-progress" label so that others will know not to start work on the issue. If you change your mind about the issue, no worries! Just let me know so that I can remove the label and free it up for someone else to claim.

Cheers!

[clemmy]

@bvaughn Upon further investigation, I'll be dropping out of this issue. ☹️ Maybe later on when I have more bandwidth.

[bvaughn]

Cool 👍 Thanks for the update

[alexkrolick]

It seems like this is mostly a question of how the docs are hosted, rather than something that can be addressed by open-source contributors (aside from potentially adding a dropdown with links to old versions and some build tweaks).

I'd envision a static hosting structure like this:

/              symlink to /latest
/latest/       symlink that gets updated to latest version periodically
/v16.x.x/      current docs go here
/v15.x.x/      old docs

Ideas:

• Use a client-side router with a dynamic root
• Static root-relative links /tutorial/tutorial.html could be replaced at build time (this isn't great because the docs have to be rebuilt when moving folders around)
• Root-relative links could be manually replaced with relative links, and the whole issue is just a matter of static hosting.
• Host previous major versions on a subdomain: v15.reactjs.org/

Also - it seems that React-Native (https://facebook.github.io/react-native/releases) has managed this from the beginning, might be worth checking what they did.

[consultwithmike]

@bvaughn I'm in for helping you make this happen. What's the best way for us to chat?

[danoc]

Been thinking a bit about this issue for Thumtack's design system. We also use Gatsby and host our site on Netlify.

Since Netlify provides a permanent link to each deploy, I'd be able to set up redirects so that example.com/input/2.0.2 redirects to 9293091-example.netlify.com/input/2.0.2.

I haven't thought much about how I will create the list of redirects though. Maybe use Netlify's API or listen for their deploy webhooks?

Another option is to use Netlify's branch deploys feature to create a subdomain for the documentation at each version release.

[bvaughn]

Hi folks 👋 I haven't really thought about this since I wrote the issue.

We can chat here on the issue. I don't have much time to dedicate to this at the moment, but I would love to see if done so if there's interest on your side- let's make it happen!

I think using the Netlify redirect API is a pretty interesting take on this, actually. 😄 At first glance, I like that a lot better than the configuration file idea I described!

[bvaughn]

I'm going to play around a bit with the redirect rule idea, using 5abc31d8be40f1556f06c4be (the latest version of the website before the 16.3 docs changes started merging in).

[consultwithmike]

@bvaughn awesome! Looking forward to hearing how it works!

[a7madgamal]

soooo any updates? Thanks!

[bvaughn]

This is already rolled out on the site: https://reactjs.org/versions

Looks like I just forgot to close the issue.

[a7madgamal]

Thanks. But I can't find the docs for 15.xx I even tried to create the link myself but it didn't work

[bvaughn]

That's because the new version of the website was rolled out with the release of version 16. As a result, we have no 15.x version fo the docs to link to. Sorry for the inconvenience!

[jaredp]

using site search on an older version of the react docs takes you to the latest version, silently

[bvaughn]

Yup. That's a limitation of our integration with Algolia.

[lukkea]

So, am I right in understanding that, as of the launch of the new website, docs for pre-16 versions are no longer available except via wayback machine?

[bvaughn]

Yes.

[vineetsagar7]

Is there a way to get react 15 docs? I want to use ref in react 15 but not able to crack it.

[bvaughn]

Is there a way to get react 15 docs?

This was answered just a few questions up:

the new version of the website was rolled out with the release of version 16. As a result, we have no 15.x version fo the docs to link to. Sorry for the inconvenience!

I understand by the number of 👎and 😕that there's a lot of frustration about this, but the React docs were never versioned before v16 either. We only recently added versions, the we couldn't (without a lot of work) go back and retroactively make it work for older versions of the website.

If anyone in the community would like to take up this effort, that would be great. The core team is small though and has limited bandwidth.

In the meanwhile, you can access older versions of the site using web.archive.org.

[cphoover]

"I understand by the number of -1 and confusedthat there's a lot of frustration about this, but the React docs were never versioned before v16 either."

Then there should be a link to pre v16 docs snapshot. Linking people to wayback machine is not a legitimate answer. Or if that is the recommended course of action, at least make this clear in the current docs.

Also there is no reason why algolia can't hold multiple indices for multiple versions.

[atwright147]

Could you at least create some links to each version on web.archive.org, so that developers don't have to find it themselves?

[bvaughn]

Then there should be a link to pre v16 docs snapshot. Linking people to wayback machine is not a legitimate answer.

Replies like this can be a little frustrating. The core team is very small and we have to juggle a lot of things. There as no versioning for the previous (v15) website. The only docs available were the latest. When I created the new website, it was to accompany the v16 released– and I was able to use Netlify's infrastructure to add versioning in so previous minor releases of v16 would have permanent docs links.

It's unfortunate that this wasn't able to cover v15 docs, but it is what it is. None of us can go back and retroactively change that. At least now we have some versioned docs, right?

All of the work we (on the core team) do is in the open though– meaning that everyone reading this issue has access to all of the same stuff we (on the core team) do. If you believe lack of v15 docs is a serious problem, and if you're able to, I'd love for you to invest some time into a finding a solution for this.

Could you at least create some links to each version on web.archive.org, so that developers don't have to find it themselves?

Anyone reading this issue could submit a PR that does this, if they'd like to! All you'd need to do is dig up the links and modify the versions.yml file.

[natevw]

Maybe this will help someone else… the reference I most frequently find myself needing is the component lifecycle methods, which were one of the biggest changes in v16!

AFAICT I found the last crawl of the v15 Component Specs and Lifecycle documentation before it turned into a redirect to the v16 equivalent. From the sidebar of that one can get other low-level v15 documentation pages as well [though those links may not reflect the last archived edits of their respective pages].

[mknmohit]

For react v15.6.2 you can find the cloned documentation here https://react-legacy.netlify.app/