Lucene-Net-Documentation.yml

# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.

name: 'Lucene.Net.Documentation'

# This will:
# checkout this repo
# get current or latest tag to parse a version for use in the docs
# change to docs/VERSION branch
# Build the docs

# Checkout the website repo
# Create a branch
# Commit/Push to the branch
# Create a PR

# push the docs/VERSION branch

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_*
    # 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
  # Or if not tag is specified, the latest Lucene.Net_4_8_0_beta00013 release tag will be used
  # which will be parsed to create the version number used in the docs like 4.8.0-beta00013
  CURRENT_TAG: "NO-VERSION"
  RELEASE_VERSION: "(no tag)"
  SITE_REPO: "${{ github.repository }}-site"
  GIT_MAIN_REPO:  "${{ github.workspace }}\\main-repo\\.git"

jobs:
  build:
    runs-on: windows-latest
    steps:

      # Checkout the main repo with all history so we get all tags
      - name: Checkout Lucene.Net source
        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          path: main-repo
          fetch-depth: 0

      - name: Set version from ref
        run: |
          # initialize to SHA
          echo ("CURRENT_REF=" + $Env:GITHUB_SHA) >> $env:GITHUB_ENV

          $ref = $Env:GITHUB_REF

          if ($ref.StartsWith("refs/heads/docs/")) {

              $version = $ref.Substring("refs/heads/docs/".Length)

              echo "Detected docs branch version: $version"

              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

      # 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: '8.0.x'

      - name: Setup .NET 10 SDK
        uses: actions/setup-dotnet@9a946fdbd5fb07b82b2f5a4466058b876ab72bb2 # v5.3.0
        with:
          dotnet-version: '10.0.x'

      - name: Build docs
        run: ./main-repo/websites/apidocs/docs.ps1 -Clean -LuceneNetVersion ${{ env.RELEASE_VERSION }}
        shell: powershell

      - name: Upload apidocs as build artifact
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        if: ${{always()}}
        with:
          name: 'apidocs'
          path: '${{github.workspace}}/main-repo/websites/apidocs/_site'

      - name: Checkout Lucene.Net website
        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          repository: ${{ env.SITE_REPO }}
          ref: asf-site
          path: website-repo

      - name: Copy documentation site files
        run: Get-ChildItem -Path "$Env:GITHUB_WORKSPACE\main-repo\websites\apidocs\_site" | Copy-Item -Destination "$Env:GITHUB_WORKSPACE\website-repo\docs\$Env:RELEASE_VERSION" -Recurse -Force
        shell: powershell

      # Always push to the same branch based on the CURRENT_TAG (latest version tag)
      # Because we are always building the docs against a consistent version
      - name: Create Pull Request
        id: cpr
        uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8
        with:
          token: ${{ secrets.LUCENE_NET_WEBSITE_BUILD }}
          path: website-repo
          commit-message: New documentation version built
          committer: GitHub <noreply@github.com>
          author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
          branch: ${{ env.PR_BRANCH }}
          delete-branch: true
          title: 'New documentation version built ${{ env.PR_BRANCH }}'
          body: |
            New documentation version built from ${{ github.sha }}
            - For version ${{ env.RELEASE_VERSION }}

      - name: Check outputs
        run: |
          echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}"
          echo "Pull Request URL - ${{ steps.cpr.outputs.pull-request-url }}"

      # TODO: Commit and push docs branch