RFC: Docs Versioning

[willihay]

Summary

This project is a follow up to the RFC for the separation of main and development branches that was implemented earlier this year.

As O3F continues to release versions of the O3DE product and moves towards long term support (LTS) of these versions, it has become clear that the o3de.org website needs a docs versioning strategy to solve the following problems:

• Readers who have installed a specific release of O3DE want docs that reflect the state of O3DE in that version. When that version moves into LTS and is no longer the current release version, we will need to preserve that version of the docs, separate from the newer docs.
• As engineers make changes to the O3DE development branch, they document new features and updates in the development branch of the website. These engineers and other early adopters want a convenient way to view these new docs.
• During the multi-week stabilization for a new release, the upcoming docs for that release should be frozen while work continues separately in the development branch.
• We may want search engines to return results only from the latest released version of the engine, instead of older versions or the development version.

What is the relevance of this feature?

Why is this important?

For the purpose of LTS, we want to provide and preserve multiple doc version sets.

What are the use cases?

Readers want to easily browse and search docs that are relevant to the version they have installed or have built.

What will it do once completed?

Readers can use a docs version selector mechanism (e.g. drop-down selector box) to switch to the doc version set of interest to them. The version remains selected as they navigate through any of the guides and topics. Ideally, their browser remembers the last selected version for future visits (e.g. through the use of cookies).

What are the advantages of the feature?

• Multiple docs version sets are readily available to O3DE users, including some topics that are "hot off the press" in the development branch, available months before their official release.
• Switching between any of the docs version sets to browse and search the versions that interest you becomes easy, without having to manually type in and bookmark all the various URLs.
• Older docs version sets remain available, even after new releases are published.

What are the disadvantages of the feature?

• Some amount of additional website maintenance is expected every time a new docs version set becomes available.
• Preserving multiple branches takes up GitHub repo space. This has not posed a problem yet, and it's not clear it ever will.
  • GitHub, for example, recommends that repos be kept under 5 GB, but only for performance reasons. Using the git-sizer tool on the o3de.org repo, we appear to be healthy and within reasonable limits overall.
  • Netlify has no documented limit on the number of branches it will publish. (Refer to Netlify docs on branches and deploys and pricing and features.)
  • However, if this does ever become a problem, we have solutions such as Git LFS that could be used for large files such as images and videos, and which could be implemented independently from the versioning solution proposed here.

Feature design description

The default website experience (without any cookies set), as published from the main branch of the o3de.org repo, will continue to reflect the docs version set that pertains to the latest release version of O3DE. Additional doc set versions, pertaining to other branches including development, staging, and earlier releases of O3DE, will be available through a version selector that's visible on all pages that fall under o3de.org/docs.

The version selector is not needed on pages outside of this directory structure, since versioning is either not needed (e.g. no need to view earlier home and community pages), or will have unique versioning rules (e.g. obtaining earlier downloads).

When a version is selected, the URL for that version will be opened. Our static site generator, Netlify, can publish any branch that we want. Each published branch will be available using a specific URL. As part of the version selection process, a functional cookie will be set to preserve the selected version for future visits by the user on that web browser.

When readers view versions of the docs that are NOT from the default version, an appropriate banner will appear at the top of every page alerting them to this fact.

Technical considerations

Branch dynamics

Docs contributors will need to be informed about the process and procedure for submitting PRs in this versioned environment.

1. Contributors to the development branch of the source repo will typically target their PRs to the development branch of the docs repo. (This pattern is in place today.)

2. At the start of stabilization for the next release, a staging branch will be created or updated. It will contain all commits/changes intended for the next release, and will be included in the list of published branches in Netlify and available versions in the version selector.

3. As part of a release, the following occurs:

   • A new branch is created from main to reflect the previous version.
   • The new branch is added to the list of published branches in Netlify.
   • Main is updated from staging.
   • A PR is created to update the static API docs in main.

4. Updates to docs branches for earlier versions of O3DE can be made on a case-by-case basis, as LTS requires.

Branch URL

Currently, we publish docs from main and development branches. Main is configured as the "production branch" in Netlify, which allows us to assign o3de.org as its URL. However, the URL for non-production branch deploys, such as development, is not as intuitive by default. For example, the URL for the development doc set is currently development--o3deorg.netlify.app/.

A more elegant solution supported by Netlify is to use branch subdomains, which would allow us to publish to simple subdomains of o3de.org, such as development.o3de.org. (We might even want to use a shorter URL like dev.o3de.org.)

However, this requires additional configuration. The recommended configuration requires the use of Netlify DNS. There is no additional cost for this feature, and setting up new branches is virtually hassle free, touted by Netlify as "single click setup". However it requires some degree of trust and authority to be given to Netlify in order for them to manage the SSL cert registration and renewal for all published branches.

There is another configuration option, but it requires a lot more manual work to set up a new branch. According to a Netlify article on using Netlify's branch deploy feature without Netlify DNS, this includes creating the DNS record to point to the Netlify branch record and contacting Netlify technical support to provision an updated SSL certificate.

🟨 We will need to work with O3F and Netlify to figure out which option can be used. 🟨

Version selector

The version selector will need to be populated from an approved list of branches. We should use short names (aliases) in the version selector box, such as "Current release", "22.05", "Staging", and "Development". Each alias will map to a URL. Note that Netlify deploy contexts might help with the implementation of this. Using deploy contexts, you can override options on a per-branch basis, including build commands and environment variables.

In regards to setting a cookie, any time a cookie is used by a website, it is important to consider user privacy laws such as GDPR and whether or not a user interface needs to be provided for clearing the cookie. According to a Cookiebot article on this topic:

| The EU cookie law (ePrivacy Directive) covers any kind of technology that process personal data from users online and uses “cookies” as an umbrella term. However, it also clearly states that the cookies deemed to be strictly necessary for the most basic functions of a website are exempt from the prior consent requirement (such as cookies that manage the contents of a user’s shopping cart on a web shop).

Scope of work

The following work has been identified:

1. Add a version selector box to the design of all pages that will publish under o3de.org/docs. This includes content from /content/docs and /static/docs. Selecting a value in the selector box should set a cookie and load the new URL.
2. Implement a design that can populate the version selector box.
3. Update robots.txt as necessary to exclude all doc versions except latest (main).
4. Work with O3F infrastructure to either set up Netlify DNS or get DNS records created and SSL certs provisioned for the subdomain branches.
5. Update the documentation on contributing to docs to explain the branch dynamics rules outlined earlier.

Include an estimation of the scope of work, so the SIG can determine if it can be reduced to a single issue (or small set of issues) an individual can perform, or if it needs to be a coordinated effort as an official SIG project.

Are there any alternatives to this feature?

• An alternative is to do nothing to the website design and continue creating branches in GitHub. For versions of the docs other than the current release, we could publish a list of their URLs on a page somewhere. However, this is unconventional for game engine documentation, and could be seen as unprofessional.

Are there any open questions?

• Will O3F infrastructure grant the appropriate DNS rights to Netlify to support the use of Netlify DNS and make creating branch subdomains with intuitive URLs a simple one-click process?
• Who from O3F infrastructure will work with the documentation SIG in a timely fashion to implement the DNS-related portions of the solution?
• How will this affect the new website design, if at all?

[willihay]

Pre-RFC discussion topic: https://github.com/o3de/sig-docs-community/discussions/46 (although there was no active discussion)

[nick-l-o3de]

Perhaps we (O3DE/DOCS-SIG) could do the dropdown up front, collect data about usage patterns and other things, and once it becomes necessary, we could schedule and work with the LF to get the DNS set up? It may inform us better on what DNS is required. In which case the scope of work could update to reflect that incremental set of steps (get the dropdown first, collect data, then get the DNS set up)

[kberg0]

Agreed, I see a lot of value in the pulldown menu. This mirrors a lot of other technical documentation sites that I find quite helpful.

The DNS feature seems subject to a lot of unknowns, and I'm not certain how much value it would ultimately bring. I don't expect customers to memorize a bunch of different urls or dns names. Instead I'd expect they'd google search, keep browser bookmarks, and navigate from whatever docs page they land on. For googling or bookmarks it doesn't much matter if you have subdomains set up.

[sptramer]

This RFC has been accepted under the following conditions:

• "Friendly" subdomains on o3de.org for redirection will not be established as part of this RFC's work; We agree that having improved subdomains is good, but not necessary for acceptance, although we would like to have them at a near-future point.