update documentation workflow to only publish one version per major

[erohmensing]

Goal

We want to have only one version of the docs per major release. That means that there will be a 2.x docs and a 3.x docs. The 2.x docs will come from the current 2.8 docs, as @m-vdb has already worked on getting the various other 2.x docs merged into this latest branch of the documentation

Updates to older branches

• The 2.8.x branch is the source of truth for the version 2 docs -- any changes that go into that branch can have documentation changes. The workflow should build the documentation whenever there is a new patch release on 2.8.x (not for every push to the .x branch, @m-vdb could clarify this to make sure I understood correctly).
• Older 2.x branches, like 2.7.x etc, should have the build documentation workflow disabled.
• Whenever we're ready, we can build the existing docs from that 2.8.x branch -- we don't need to wait for 3.0 to come out to get this in play.

Updates for 3.0 docs

• For 3.x docs, we are planning to have only one set of documentation, marking changes over time in the docs directly with callouts (e.g. "added in 3.1" in the docs pages themselves, as well as the regular changelog). That means that we only want to build the docs from releases on the latest minor.
  • I.e. when we are on 3.0.x, we build the docs off of the 3.0.x branch every time we release a new micro. Upon release of 3.1.0, the workflow should build the docs only from the 3.1.x branch, and shouldn't build docs on any micros added to 3.0.x (ideally people are not merging to this, but if they are, it is due to specific backported fixes that those using them are aware of -- docs for backported fixes create confusion as to which later versions of the code the fix is in, so we'll avoid that as much as possible)

[m-vdb]

the original scoping document I wrote is here. Under the "Release branches" section, you'll find different considerations, with the only viable solution highlighted in green

[m-vdb]

(not for every push to the .x branch, @m-vdb could clarify this to make sure I understood correctly)

this is correct

Whenever we're ready, we can build the existing docs from that 2.8.x branch -- we don't need to wait for 3.0 to come out to get this in play.

we'll also need to manually update the documentation branch with the latest changes from 2.8.x before we activate the workflow (I will take care of it). I did that for all minors from 2.0 to 2.7 included, and deliberately waited for the workflow to be ready to do that for 2.8 (otherwise new micros released on 2.8 would have made it complicated to keep the source of truth intact).

To summarise the final state we're aiming at:

• docs are built on every minor tag for the latest major (when 3.0 is out, the latest major is 3.0)
• docs are built on every micro tag for the latest minor of
  • the latest major (when 3.0 is out, the latest major is 3.0)
  • the previous major (when 3.0 is out, the previous major is 2.0, the latest minor on this version being 2.8)

[tczekajlo]

Cool, my plan is to take care of it next week

[erohmensing]

closed + released!!