RFC: React-Native docs version archiving workflow

slorber commented 1 year ago

Description

Older React-Native docs versions do not receive docs updates anymore, and should rather be "archived".

By "archived", I mean stored permanently to a standalone immutable deployment, that will remain accessible forever. Users of a popular React-Native version (ex: 0.64 with > 5% usage currently) should keep access to the older docs.

In this RFC, the goal is to discuss the process to adopt, so that site maintainers can archive older versions easily.

What is the problem?

The current React-Native website contains versions from 0.73 to 0.60: that's a lot of versions.

Having many versions increase website production build times
Versions <= 0.67 do not even appear in the versioning dropdown
Versions <= 0.67 barely receive any docs updates, apart some minor versions-wide backports

Good reasons to archive older versions:

reduce production build time
reduce site maintenance work
declutter the repo

In https://github.com/facebook/react-native-website/pull/3818, I proposed to archive versions <= 0.67.

It works but it is not ideal for a few reasons:

I did it, but I didn't teach you how to do it on your own
There are now 2 Netlify Meta deployments with archived versions: https://archive.reactnative.dev/ and https://reactnative-archive-august-2023.netlify.app/

How can we address it?

There are multiple ways to archive versions, each way present different tradeoffs. So I'm going to present you the options, and let you choose the one you'd prefer to use.

Shared Process

For all the options I propose, a good base of the process remains common/shared.
The part that is different is mostly how/where you store the archived.

Overview

For all of the proposed options, the general idea consists of:

Building the site locally from an up-to-date main branch
Storing/deploying the website/build static output somewhere permanently
Getting a permalink of the archived versions
Adding archived versions external permalink to the reactnative.dev/versions page
Removing the archived versions from the production site and repo: cleanup versions.json + versioned_docs/version-<0.x> + versioned_sidebars/version-0.<x>-sidebars.json)

Single clean sub-domain?

It is optional, but would look better if all the archived websites would live under a clean domain name (like the existing https://archive.reactnative.dev/) instead of using CDN permalinks (Netlify/Vercel deployment urls), or having to create a new domain with DNS settings everytime you want to archive a version.

Creating the static assets with Docusaurus

Technically, it is possible to create a CLI or shell script that builds a RN site from/to specific versions, or building the RN site with just a single version. Example commands we could provide:

ARCHIVE_FROM=0.60 ARCHIVE_TO=0.67 yarn docusaurus build
ARCHIVE_FROM=0.67 ARCHIVE_TO=0.67 BASE_URL="/0.67/" yarn docusaurus build

If you build each version under different base-urls, it is possible to "merge" all the static folders into a single deployment.

The final result could be something like:

archive.reactnative.dev/0.67/*
archive.reactnative.dev/0.66/*
archive.reactnative.dev/0.65/*
archive.reactnative.dev/0.60-0.65/*
archive.reactnative.dev/older-versions/* (< 0.60)

It is up to you if you want to archive multiple versions at once, or create one website archive per version.

Deployment Options

Option 1 - create a `website-archive` branch on this repo

The idea is to create a website-archive branch where you put all the static content

👍 Can be managed from this repo directly 👎 Requires putting megabytes of static content in this Git repo

Note: there is already an archive branch: it is the old Docusaurus v1 website source code, that triggers the build of https://archive.reactnative.dev/. This proposal is different: it suggests to just put the pre-built static assets on the Git branch, so that Netlify can deploy the website-archive branch as-is, without having to build anything.

Option 2 - Create a new repo for the archives

Instead of creating a website-archive branch, it is possible to use the main branch of a facebook/react-native-website-archive repo and store the pre-built static content there.

👍 Megabytes of static content are isolated to a standalone Git repo 👎 Requires a new Git repo to manage

Option 3 - Create a new CDN deployment per archive

This is the solution I used while deploying this website: https://reactnative-archive-august-2023.netlify.app/

You can create a new CDN deployment with a custom CDN subdomain by simply drag & dropping the website/build folder to Netlify.

It is possible to obtain cleaner urls by adding DNS settings, or creating a _redirects Netlify file somewhere in this repo to set up some proxy/rewrite-urls.

👍 Easy to get started 👎 Requires Netlify access, creates many archive deployments on the Netlify Meta team, requires more work to obtain clean urls.

This is the option I choose in https://github.com/facebook/react-native-website/pull/3818 because it's good enough to get started and I could make it work without any approval. But it does not look like the best long-term option, particularly if you want a clean unique archive subdomain or want to automate the archiving process with a shell script.

Conclusion

This RFC opens the discussion.

I'd be happy to help you set this up and create a very simple step-by-step process once you decide which option you prefer.

slorber commented 1 year ago

cc @zpao I think this Docusaurus version archiving process could be useful for other Meta Open Source sites as well.

Maybe you'll want to normalize this process all the sites?

chriszs commented 1 year ago

Appreciate the work. When I was adding the URL to a project's documentation, the naming didn't instill a lot of confidence that this will be accessible in the future. An archive to me implies some degree of permanence. reactnative-archive-august-2023 feels like a temporary preview branch and netlify.app is specific to a hosting provider. I can see the URL already slipping into project documentation in several other places.

github-actions[bot] commented 9 months ago

👋 Hey there, it looks like there has been no activity on this issue in the last 90 days. Has the issue been fixed, or does it still require the community attention? This issue will be closed in the next 7 days if no further activity occurs. Thank you for your contributions.

github-actions[bot] commented 6 months ago

👋 Hey there, it looks like there has been no activity on this issue in the last 90 days. Has the issue been fixed, or does it still require the community attention? This issue will be closed in the next 7 days if no further activity occurs. Thank you for your contributions.

slorber commented 6 months ago

Does anyone want to decide on this?

github-actions[bot] commented 3 months ago

👋 Hey there, it looks like there has been no activity on this issue in the last 90 days. Has the issue been fixed, or does it still require the community attention? This issue will be closed in the next 7 days if no further activity occurs. Thank you for your contributions.

github-actions[bot] commented 3 months ago

Closing this issue after a prolonged period of inactivity. If this issue is still present in the latest release, please feel free to create a new issue with up-to-date information.

facebook / react-native-website