Docs Updating Process

[ShaunaGordon]

Summary

The versioning and release process of the docs site has come up a few times in recent discourse. There are some differing opinions on how it should be handled, and at this point, I think it would be beneficial to hammer things out here and come up with a process that's both sane for us, and that works with our needs, both as an independent part of the broader O3DE project and as a linked part of it.

The Problem

Currently, the docs release process is as follows:

1. A feature branch is cut off from development and worked on
2. A PR is opened, targeting development, and merged into it when approved
3. development collects PRs until an engine release
4. A cherry-picking branch is cut from main, and commits are cherry-picked from development into it
5. The cherry-picking branch is merged into main when an engine version is released, with a corresponding version indicator

This works okayish, particularly for docs additions for new features, which logically need to be released only with the release of the corresponding engine version. However, because the docs are ever-evolving and don't document every single thing of the engine, it's more common for the docs to be updated with things that don't need to be locked to a new engine release and arguably should be added to the current version sooner rather than later.

Proposal

I opened this discussion to talk through various potential solutions, but here are a few thoughts I've had for how to go about this.

Back to the old way

The first possible solution is to go back to the old way, where PRs are first opened against development, then upon approval, copied to main. This had the benefit of updating the main site immediately, at the expense of additional work to do the cherry-pick each time.

During the time this method was used, there were also a lot of commits that went into main, but didn't make it into development. I don't think that happened as a result of this flow, but I do think that the higher frequency of going to main makes this prone to happen more often, especially as it's difficult to adequately lock down the branches with Github's new branch protection interface.

A new way: periodic batching

The new solution that I propose for consideration is a sort of in-between what we had before and what we have now. Instead of waiting for releases or cherry-picking every time, we go in every couple of weeks or so, or after some number of PRs, and we do the cherry-pick process that we do now, but not in lockstep with the engine.

This has the benefit of updating the docs for the current version more frequently, so the cherry-pick PRs are smaller, but it's not a cherry-pick PR for every single submission.

Automation?

Another option to look into is an automated or semi-automated way to cherry-pick the changes over. This would need to be tied to some sort of tag or keyword in the PR to help control it, but it could help to reduce the amount of manual work. Github Actions can be set up to trigger on PR merge close, pick up on whatever keyword, then open a cherry-pick PR against main. It can either then automatically merge it, or stop there to allow human interaction and approval (which is probably what we'd do at first, regardless, to prove it out).