Repository: RasaHQ/rasa
Pull request: Update documentation workflow to only publish one version per major
**Proposed changes**:
- Resolves #9711 

**Status (please check what you already did)**:
- [ ] added some tests for the functionality
- [ ] updated the documentation
- [ ] updated the changelog (please check [changelog](https://github.com/RasaHQ/rasa/tree/main/changelog) for instructions)
- [ ] reformat files using `black` (please check [Readme](https://github.com/RasaHQ/rasa#code-style) for instructions)


Problem statement:
update documentation workflow to only publish one version per major
**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)

Hints from issue discussion:
the original scoping document I wrote is [here](https://www.notion.so/rasa/Doc-versions-for-Majors-only-caaf78eadff34d7d8b49eb2284ccc8f9#ef96a397d21a42ae9d0ba0a82494e901). Under the "Release branches" section, you'll find different considerations, with the only viable solution highlighted in green
> (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)
Cool, my plan is to take care of it next week

Commit message: improvements

Signed-off-by: tczekajlo <t.czekajlo@rasa.com>

Patch to review:
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
index 00c8595fdec0..b9b6ac79a41d 100644
--- a/.github/workflows/documentation.yml
+++ b/.github/workflows/documentation.yml
@@ -15,12 +15,85 @@ on:
 env:
   DOCS_FOLDER: docs
   DOCS_BRANCH: documentation
+  TAG_NAME: ${GITHUB_REF#refs/tags/}
+  IS_TAG_BUILD: ${{ startsWith(github.event.ref, 'refs/tags') }}
+  IS_MASTER_BRANCH: ${{ github.ref == 'refs/heads/main' }}
 
 jobs:
+  evaluate_release_tag:
+    name: Evaluate release tag
+    runs-on: ubuntu-latest
+    if: github.repository == 'RasaHQ/rasa'  # don't run this for main branches of forks, would fail anyways
+    outputs:
+      build_docs: ${{ steps.check_tag.outputs.build_docs }}
+
+    steps:
+    - name: Checkout git repository 🕝
+      uses: actions/checkout@v2
+
+    - name: Check if tag version is equal or higher than the latest tagged Rasa version
+      id: rasa_get_version
+      run: |
+        # Get latest tagged Rasa version
+        git fetch --depth=1 origin "+refs/tags/*:refs/tags/*"
+        # Fetch branch history
+        git fetch --prune --unshallow
+        LATEST_TAGGED_NON_ALPHA_RASA_VERSION=$(git tag | sort -r -V | grep -E "^[0-9.]+$" | head -n1)
+
+        echo "LATEST_TAGGED_NON_ALPHA_RASA_VERSION=${LATEST_TAGGED_NON_ALPHA_RASA_VERSION}" >> $GITHUB_ENV
+
+        # Return 'true' if tag version is equal or higher than the latest tagged Rasa version
+        IS_LATEST_VERSION=$((printf '%s\n%s\n' "${LATEST_TAGGED_NON_ALPHA_RASA_VERSION}" "$TAG_NAME" \
+          | sort -V -C && echo true || echo false) || true)
+
+
+        if [[ "${IS_LATEST_VERSION}" == "true" && "$TAG_NAME" =~ ^[0-9.]+$ ]]; then
+          echo "::set-output name=is_latest_version::true"
+        else
+          echo "::set-output name=is_latest_version::false"
+        fi
+
+
+    # MAJOR.MINOR.MICRO(PATCH)
+    # docs are built on every minor tag for the latest major (when 3.0 is out, the latest major is 3.0)
+    # (technically it'll be always the latest version)
+    #
+    # 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)
+    - name: Check if it's a micro tag for the latest minor
+      if: env.IS_TAG_BUILD == 'true'
+      id: check_tag
+      run: |
+        IS_LATEST_VERSION=${{ steps.rasa_get_version.outputs.is_latest_version }}
+
+        # the latest major (when 3.0 is out, the latest major is 3.0)
+        # build docs on push to the main branch
+        if [[ "${IS_LATEST_VERSION}" == "true" || "${IS_MASTER_BRANCH}" == "true" ]]; then
+          echo "::set-output name=build_docs::true"
+          exit 0
+        fi
+
+        # the previous major (when 3.0 is out, the previous major is 2.0, the latest minor on this version being 2.8)
+        CURRENT_MAJOR_VERSION=$(echo ${LATEST_TAGGED_NON_ALPHA_RASA_VERSION} | awk -F\. '{print $1}')
+        PREVIOUS_MAJOR_LATEST_VERSION=$(git tag | sort -r -V | grep -E "^[0-9.]+$" | grep -vE "^${CURRENT_MAJOR_VERSION}" | head -n1)
+
+        # Return 'true' if tag version is equal or higher than the latest previous major version
+        IS_PREVIOUS_MAJOR_LATEST_VERSION=$((printf '%s\n%s\n' "${PREVIOUS_MAJOR_LATEST_VERSION}" "$TAG_NAME" \
+          | sort -V -C && echo true || echo false) || true)
+
+        if [[ "${IS_PREVIOUS_MAJOR_LATEST_VERSION}" == "true" ]]; then
+          echo "::set-output name=build_docs::true"
+          exit 0
+        fi
+
+        echo "::set-output name=build_docs::false"
+
   docs:
     name: Build Docs
     runs-on: ubuntu-latest
-    if: github.repository == 'RasaHQ/rasa'  # don't run this for main branches of forks, would fail anyways
+    needs: [ evaluate_release_tag ]
+    if: github.repository == 'RasaHQ/rasa' && needs.evaluate_release_tag.outputs.build_docs == 'true'  # don't run this for main branches of forks, would fail anyways
 
     steps:
     - name: Checkout git repository 🕝
diff --git a/scripts/push_docs_to_branch.sh b/scripts/push_docs_to_branch.sh
index 8009fdd351dc..4674bd449d9a 100755
--- a/scripts/push_docs_to_branch.sh
+++ b/scripts/push_docs_to_branch.sh
@@ -14,7 +14,7 @@ set -Eeuo pipefail
 
 TODAY=`date "+%Y%m%d"`
 # we build new versions only for minors and majors
-PATTERN_FOR_NEW_VERSION="^refs/tags/[0-9]+\\.[0-9]+\\.0$"
+PATTERN_FOR_NEW_VERSION="^refs/tags/[0-9]+\\.0\\.0$"
 PATTERN_FOR_MICRO_VERSION="^refs/tags/[0-9]+\\.[0-9]+\\.[1-9][0-9]*$"
 MAIN_REF=refs/heads/main
 VARIABLES_JSON=docs/docs/variables.json
@@ -33,10 +33,12 @@ NEW_VERSION=
 EXISTING_VERSION=
 if [[ "$GITHUB_REF" =~ $PATTERN_FOR_NEW_VERSION ]]
 then
-    NEW_VERSION=$(echo $GITHUB_REF | sed -E "s/^refs\/tags\/([0-9]+)\.([0-9]+)\.0$/\1.\2.x/")
+    NEW_VERSION=$(echo $GITHUB_REF | sed -E "s/^refs\/tags\/([0-9]+)\.([0-9]+)\.0$/\1.x/")
+    if [[ -n ${CI} ]]; then echo "New version: ${NEW_VERSION}"; fi
 elif [[ "$GITHUB_REF" =~ $PATTERN_FOR_MICRO_VERSION ]]
 then
-    EXISTING_VERSION=$(echo $GITHUB_REF | sed -E "s/^refs\/tags\/([0-9]+)\.([0-9]+)\.[0-9]+$/\1.\2.x/")
+    EXISTING_VERSION=$(echo $GITHUB_REF | sed -E "s/^refs\/tags\/([0-9]+)\.([0-9]+)\.[0-9]+$/\1.x/")
+    if [[ -n ${CI} ]]; then echo "Existing version: ${EXISTING_VERSION}"; fi
 fi
 
 # clone the $DOCS_BRANCH in a temp directory


Code review comments:
diff_hunk: @@ -14,7 +14,7 @@ set -Eeuo pipefail
 
 TODAY=`date "+%Y%m%d"`
 # we build new versions only for minors and majors
-PATTERN_FOR_NEW_VERSION="^refs/tags/[0-9]+\\.[0-9]+\\.0$"
+PATTERN_FOR_NEW_VERSION="^refs/tags/[0-9]+\\.0\\.0$"
 PATTERN_FOR_MICRO_VERSION="^refs/tags/[0-9]+\\.[0-9]+\\.[1-9][0-9]*$"
path: scripts/push_docs_to_branch.sh
text: @user1:
```suggestion
PATTERN_FOR_EXISTING_VERSION="^refs/tags/[0-9]+\\.[0-9]+\\.[0-9]+$"
```

🤕 sorry for not spotting this one earlier... We need to change this pattern to match new minors too, now (e.g. 3.1.0, etc...). I think it's the last change required, I've doubled check the full logic and it seems in order ✅