Updated Docs and Website Automation Trigger + Procedures

.github/workflows/Lucene-Net-Documentation.yml

@@ -33,13 +33,19 @@ name: 'Lucene.Net.Documentation'
 on:
   workflow_dispatch:
   push:
+    # 2026-06-23 - when both tags and branches are used, they are ORed. However, note that when paths is used, it is ANDed to each of them.
     tags:
     - Docs_*
-    #branches:
-    #- master
-    paths:
-    - 'websites/apidocs/**/*'
-    - 'src/docs/LuceneDocsPlugins/**/*'
+    # 2026-06-23 - the docs/** branch is the source of truth for each docs site build. Those branches must be carefully managed to ensure that nothing is committed
+    # to them that deviates from the state of the API at the time of the release. Updates to the spelling or explanation of an API are usually okay. Updates to the
+    # API parameter lists or other criteria that define the public signature are not.
+    branches:
+    - docs/**
+    # 2026-06-23 - the docs/** branches should be "filtered" manaually to ensure no unwanted changes are ever committed. But if so, the PR that this automation
+    # creates can be rejected and the errantly committed changes can be reverted before rebuilding the API docs site.
+    #paths:
+    #- 'websites/apidocs/**/*'
+    #- 'src/docs/LuceneDocsPlugins/**/*'
 
 env:
   # If a tag is specified, the tag will be in the format: Docs_4_8_0_beta00013
@@ -62,71 +68,113 @@ jobs:
           path: main-repo
           fetch-depth: 0
 
-      - name: Set version from tag
+      - name: Set version from ref
         run: |
           # initialize to SHA
-          echo ("CURRENT_TAG=" + $Env:GITHUB_SHA) >> $env:GITHUB_ENV
+          echo ("CURRENT_REF=" + $Env:GITHUB_SHA) >> $env:GITHUB_ENV
+
           $ref = $Env:GITHUB_REF
 
-          if ($ref.StartsWith("refs/tags/")) {
-            $tag = $ref.Substring(10)
-            echo "extracted tag name from refs/tags as $tag"
-          }
-          else {
-            echo "Get the latest Lucene.Net_ tag"
-            $tag = & git --git-dir "$Env:GIT_MAIN_REPO" tag --list --sort=-version:refname 'Lucene.Net_[0-9]_[0-9]_[0-9]*' | select -first 1
-          }
+          if ($ref.StartsWith("refs/heads/docs/")) {
 
-          if ($tag -eq $null) {
-            echo "::error::Could not determine current version tag"
-            exit 1
-          }
+              $version = $ref.Substring("refs/heads/docs/".Length)
 
-          # write the environment var
-          echo ("CURRENT_TAG=" + $tag) >> $env:GITHUB_ENV
-
-          $parts = $tag.Split("_")
-          $version = '';
-          For ($i=1; $i -le $parts.Length; $i++) {
-            $version += $parts[$i]
-            if ($i -eq ($parts.Length - 2)) {
-              $version += "-"
-            }
-            elseif ($i -lt ($parts.Length - 1)) {
-              $version += "."
-            }
-          }
+              echo "Detected docs branch version: $version"
 
-          if ($version -ne '') {
-            # the tag parsed to the correct version format, write the environment var
-            echo ("RELEASE_VERSION=" + $version) >> $env:GITHUB_ENV
-          }
-          else {
-            echo "::error::Could not parse current version tag"
-            exit 1
+              echo ("CURRENT_REF=" + $Env:GITHUB_REF_NAME) >> $env:GITHUB_ENV
+              echo ("RELEASE_VERSION=" + $version) >> $env:GITHUB_ENV
+          } elseif ($ref.StartsWith("refs/heads/release/")) {
+
+              $version = $ref.Substring("refs/heads/release/".Length)
+
+              echo "Detected release branch version: $version"
+
+              echo ("CURRENT_REF=" + $Env:GITHUB_REF_NAME) >> $env:GITHUB_ENV
+              echo ("RELEASE_VERSION=" + $version) >> $env:GITHUB_ENV
+          } elseif ($ref.StartsWith("refs/tags/Docs_")) {
+
+              $tag = $ref.Substring(10)
+
+              echo "Detected docs tag: $tag"
+
+              $parts = $tag.Split("_")
+
+              $version = ''
+              for ($i = 1; $i -lt $parts.Length; $i++) {
+                  $version += $parts[$i]
+
+                  if ($i -eq ($parts.Length - 2)) {
+                      $version += "-"
+                  }
+                  elseif ($i -lt ($parts.Length - 1)) {
+                      $version += "."
+                  }
+              }
+
+              echo ("CURRENT_REF=" + $tag) >> $env:GITHUB_ENV
+              echo ("RELEASE_VERSION=" + $version) >> $env:GITHUB_ENV
+          } else {
+
+              echo "No versioned branch detected. Falling back to latest Lucene.Net tag."
+
+              $tag = & git --git-dir "$Env:GIT_MAIN_REPO" tag --list --sort=-version:refname 'Lucene.Net_[0-9]_[0-9]_[0-9]*' | select -first 1
+
+              if ($tag -eq $null) {
+                  echo "::error::Could not determine current version"
+                  exit 1
+              }
+
+              $parts = $tag.Split("_")
+
+              $version = ''
+              for ($i = 1; $i -lt $parts.Length; $i++) {
+                  $version += $parts[$i]
+
+                  if ($i -eq ($parts.Length - 2)) {
+                      $version += "-"
+                  }
+                  elseif ($i -lt ($parts.Length - 1)) {
+                      $version += "."
+                  }
+              }
+
+              echo ("CURRENT_REF=" + $tag) >> $env:GITHUB_ENV
+              echo ("RELEASE_VERSION=" + $version) >> $env:GITHUB_ENV
           }
+
+      - name: Set PR branch name
+        run: |
+          $shortSHA = $Env:GITHUB_SHA.Substring(0, 7)
+
+          echo ("PR_BRANCH=docs-build-" + $Env:RELEASE_VERSION + "-" + $shortSHA) >> $env:GITHUB_ENV
         shell: powershell
 
       - name: Verify environment variables
         run: |
           echo "CURRENT_TAG=$Env:CURRENT_TAG"
+          echo "GITHUB_REF=$Env:GITHUB_REF"
+          echo "GITHUB_REF_NAME=$Env:GITHUB_REF_NAME"
+          echo "GITHUB_SHA=$Env:GITHUB_SHA"
+          echo "CURRENT_REF=$Env:CURRENT_REF"
           echo "RELEASE_VERSION=$Env:RELEASE_VERSION"
+          echo "PR_BRANCH=$Env:PR_BRANCH"
         shell: powershell
 
-      - name: Change branch
-        run: |
-          git --git-dir "$Env:GIT_MAIN_REPO" checkout -b "docs/${{ env.RELEASE_VERSION }}"
-        shell: powershell
-
-      - name: Setup .NET 6 SDK
+      # NOTE: It isn't clear why we were doing this, but removing because this could cause errors when using either docs/VERSION or release/VERSION style branches
+      #- name: Change branch
+      #  run: |
+      #    git --git-dir "$Env:GIT_MAIN_REPO" checkout -b "docs/${{ env.RELEASE_VERSION }}"
+      #  shell: powershell
+
+      - name: Setup .NET 8 SDK
         uses: actions/setup-dotnet@9a946fdbd5fb07b82b2f5a4466058b876ab72bb2 # v5.3.0
         with:
-          dotnet-version: '6.0.x'
+          dotnet-version: '8.0.x'
 
-      - name: Setup .NET 8 SDK
+      - name: Setup .NET 10 SDK
         uses: actions/setup-dotnet@9a946fdbd5fb07b82b2f5a4466058b876ab72bb2 # v5.3.0
         with:
-          dotnet-version: '8.0.x'
+          dotnet-version: '10.0.x'
 
       - name: Build docs
         run: ./main-repo/websites/apidocs/docs.ps1 -Clean -LuceneNetVersion ${{ env.RELEASE_VERSION }}
@@ -161,11 +209,11 @@ jobs:
           commit-message: New documentation version built
           committer: GitHub <noreply@github.com>
           author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
-          branch: ${{ env.CURRENT_TAG }}
+          branch: ${{ env.PR_BRANCH }}
           delete-branch: true
-          title: 'New documentation version built ${{ env.CURRENT_TAG }}'
+          title: 'New documentation version built ${{ env.PR_BRANCH }}'
           body: |
-            New documentation version built ${{ env.CURRENT_TAG }}
+            New documentation version built from ${{ github.sha }}
             - For version ${{ env.RELEASE_VERSION }}
 
       - name: Check outputs

.github/workflows/Lucene-Net-Website.yml

@@ -29,10 +29,14 @@ name: 'Lucene.Net.Website'
 on:
   workflow_dispatch:
   push:
+    # 2026-06-23 - when only tags and paths are used, they are ANDed together, not ORed, so the presence of a Website_* tag blocked the automation from triggering.
+    # Howevever, if both tags and branches are present then we have 1) tags AND paths OR 2) branches AND paths. So, we need to specify them all if we want either or.
     tags:
     - Website_*
-    #branches:
-    #- master
+    # 2026-06-23 - we purposely make the master branch the source of truth for the website, as it is supposed to contain the latest state of our project.
+    # master is always the source of truth for the website. Release branches that update website pages should cherry-pick those changes back to master.
+    branches:
+    - master
     paths:
     - 'websites/site/**/*'
 

websites/site/contributing/documentation.md

@@ -16,6 +16,29 @@ To submit changes for the website, create a Pull Request to the [Lucene Git repo
 
 ## Website
 
+### Lifecycle
+
+The source of truth of the website is on the `master` branch.
+
+```
+feature branch
+    ↓
+PR
+    ↓
+master
+    ↓
+website workflow
+    ↓
+lucenenet-site PR
+    ↓
+publish website
+```
+
+- All website changes that should be publicly visible must eventually exist on the `master` branch.
+- Release branches may temporarily contain website changes, but those changes must be cherry-picked (or in some cases merged) back to `master` if they should remain part of the published website.
+
+This ensures the website is always synched with the `master` branch and PRs that affect the website are automatically built for deployment.
+
 ### Build script
 
 To build the website and run it on your machine, run the PowerShell script: `./websites/site/site.ps1` with the `-ServeDocs` flag. For example:
@@ -60,6 +83,58 @@ The file/folder structure is within `./websites/site`:
 
 ## API Docs
 
+### Lifecycle
+
+The source of truth of an API docs build is the corresponding `docs/[PackageVersion]` branch. For example, the `docs/4.8.0-beta00017` branch is set up to build the docs for 4.8.0-beta00017.
+
+- Only documentation-related changes should be committed to docs branches.
+- Changes that apply to legacy docs versions may be cherry-picked to older docs branches to build releases for them, but this is optional.
+- Docs infrastructure changes generally are committed to `master` first, then cherry-picked to the relevant `docs` branches for release. Ensure the `master` branch contains the docs build infrastructure changes for all future docs API releases.
+
+#### Release Lifecycle
+
+```
+master
+    ↓
+release/x.y.z
+    ↓
+create docs/x.y.z
+    ↓
+cherry-pick documentation fixes
+    ↓
+push docs/x.y.z
+    ↓
+docs workflow
+    ↓
+lucenenet-site PR
+    ↓
+publish docs site
+```
+
+#### Docs Infrastructure Lifecycle
+
+```
+master
+    ↓
+feature branch
+    ↓
+PR
+    ↓
+master
+    ↓
+cherry-pick documentation infrastructure fixes
+    ↓
+checkout docs/x.y.z
+    ↓
+push docs/x.y.z
+    ↓
+docs workflow
+    ↓
+lucenenet-site PR
+    ↓
+publish docs site
+```
+
 ### Build script
 
 To build the api docs and run it on your machine, run the PowerShell script: `./websites/apidocs/docs.ps1`. For example: