Update publication CI for "develop" branch

.github/workflows/publish_v3.yml

@@ -1,7 +1,19 @@
+# Publish SPDX specification to https://spdx.github.io/spdx-spec/
+#
+# Overview:
+# 1) Generate model documents and RDFs from model files in spdx-3-model repo
+# 2) Combine the model documents from (1) with the chapters in spdx-spec repo
+# 3) Generate a website using files from (2)
+# 4) Upload RDFs from (1) and a website from (3) to GitHub Pages
+# 5) Make URL redirections as needed
+#
+# See notes on running this workflow from "support" branch at:
+# https://github.com/spdx/spdx-spec/pull/1146
+
 on:
   push:
     branches:
-      - development/v3.0.1
+      - main
   repository_dispatch:
     types:
       - publish_v3_spec
@@ -10,13 +22,20 @@ jobs:
   build:
     runs-on: ubuntu-latest
     env:
-      REF_SPEC: "development/v3.0.1"        # spec branch/tag release
+      REF_SPEC: "main"                      # spec branch/tag release
       REF_MODEL: "main"                     # model branch/tag release
       REF_PARSER: "main"                    # parser branch/tag release
       GH_PAGES_BRANCH: "gh-pages"           # branch name to publish HTML to
-      VERSION: "v3.0.1"                     # publishing version
-      VERSION_DEFAULT: "v3.0.1"             # default version (be redirected from https://spdx.github.io/spdx-spec/)
-      VERSION_ALIASES: "latest v3.0 v3.0.1-draft v3-draft v3.0-RC1 v3.0-RC2"  # aliases for VERSION
+      VERSION_DEFAULT: "v3.0.1"             # default version;
+                                            # a version to be redirected from the URL without version number specified;
+                                            # VERSION_DEFAULT should be the same across all branches/tags
+      VERSION: "v3.0.1"                     # publishing version, to be publish by this workflow
+                                            # VERSION can be different from VERSION_DEFAULT;
+                                            # for example, if VERSION is a draft or a release candidate,
+                                            # or if VERSION is a stable version that is behind the default version (e.g. 3.0.2 vs 3.1)
+      VERSION_ALIASES: "latest 3.0.1 v3.0 v3.0.1-draft v3-draft v3.0-RC1 v3.0-RC2 3.0 3.0.1-draft 3-draft 3.0-RC1 3.0-RC2"
+                                            # VERSION_ALIASES are versions that will be redirected to VERSION; separated by space
+                                            # Note that the "latest" should be reserved for the latest version
       GIT_USER_NAME: "ci-bot"               # for gh-pages commit
       GIT_USER_EMAIL: "[email protected]"     # for gh-pages commit
       PARSER_OUT_BASE_DIR: "__parser_out"   # temp dir for output from spec-parser
@@ -147,16 +166,24 @@ jobs:
           echo "===================="
       - name: Deploy and set aliases
         # mike is used here to manage multiple versions of MkDocs-powered documentation
-        # This step does 3 things:
+        # This step does 2 things:
         # 1) delete existing aliases (in VERSION_ALIASES), if exists
         # 2) deploy as VERSION, with aliases
-        # 3) set default version to VERSION_DEFAULT
+        # If the existing aliases were redirected to other versions,
+        # it means this VERSION will "steal" the aliases from those versions.
         working-directory: spdx-spec
         run: |
           for alias in $VERSION_ALIASES; do
             mike delete --config-file "$MKDOCS_FULL_YML" --branch $GH_PAGES_BRANCH --push --allow-empty "$alias" || true
           done
           mike deploy --update-aliase --config-file "$MKDOCS_FULL_YML" --branch $GH_PAGES_BRANCH --push $VERSION $VERSION_ALIASES
+      - name: Set default version
+        # Set default version to VERSION_DEFAULT;
+        # if not set, the default version will remain the same.
+        # Should only be done from the "main" branch.
+        if: github.ref == 'refs/heads/main'
+        working-directory: spdx-spec
+        run: |
           mike set-default --config-file "$MKDOCS_FULL_YML" --branch $GH_PAGES_BRANCH --push $VERSION_DEFAULT
       - name: Copy JSON annotations, JSON schema, JSON-LD context, and RDFs to alias directories
         # Fallback for backward compatibility with old URLs before v3.0.1
@@ -195,7 +222,8 @@ jobs:
         # page (index.html) under a subdirectory with the name of 'from'
         # that will refresh the browser to a URL of 'to'.
         #
-        # For example, given
+        # For example, given:
+        #
         #     VERSION          = "v3.0.1"
         #     VERSION_ALIASES  = "latest v3.0"
         #     from             = "model/Core/Properties/imports"