cd_release.yml

name: CD - Release

on:
  workflow_call:
    inputs:
      # General - REQUIRED
      git_username:
        description: "A git username (used to set the 'user.name' config option)."
        required: true
        type: string
      git_email:
        description: "A git user's email address (used to set the 'user.email' config option)."
        required: true
        type: string
      release_branch:
        description: "The branch name to release/publish from."
        required: true
        type: string
        default: main

      # General - OPTIONAL
      runner:
        description: "The runner to use for the workflow. Note, the callable workflow expects a Linux/Unix system."
        required: false
        type: string
        default: ubuntu-latest
      install_extras:
        description: "Any extras to install from the local repository through 'pip'. Must be encapsulated in square parentheses (`[]`) and be separated by commas (`,`) without any spaces. Example: `'[dev,release]'`."
        required: false
        type: string
        default: ""
      system_dependencies:
        description: "A single (space-separated) or multi-line string of Ubuntu APT packages to install prior to installing the local repository."
        required: false
        type: string
        default: ""
      relative:
        description: "Whether or not to use install the local Python package(s) as an editable."
        required: false
        type: boolean
        default: false
      test:
        description: "Whether to use the TestPyPI repository index instead of PyPI as well as output debug statements in both workflow jobs."
        required: false
        type: boolean
        default: false
      pip_index_url:
        description: "A URL to a PyPI repository index. Defaults to 'https://pypi.org/simple/'."
        required: false
        type: string
        default: "https://pypi.org/simple/"
      pip_extra_index_urls:
        description: "A space-delimited string of URLs to additional PyPI repository indices."
        required: false
        type: string
        default: ""

      # Update Python package version, build and release on PyPI
      publish_on_pypi:
        description: "Whether or not to publish on PyPI. **Note**: This is only relevant if 'python_package' is 'true', which is the default."
        required: true
        type: boolean
        default: false
      python_package:
        description: "Whether or not this is a Python package, where the version should be updated in the 'package_dir'/__init__.py for the possibly several 'package_dir' lines given in the 'package_dirs' input and a build and release to PyPI should be performed."
        required: false
        type: boolean
        default: true
      python_version_build:
        description: "The Python version to use for the workflow when building the package."
        required: false
        type: string
        default: "3.9"
      package_dirs:
        description: "A multi-line string of paths to Python package directories relative to the repository directory to have its `__version__` value updated. Example: `'src/my_package'`. **Important**: This is _required_ if 'python_package' is 'true', which is the default."
        required: false
        type: string
        default: ""
      version_update_changes:
        description: "A multi-line string of changes to be implemented in the repository files upon updating the version. The string should be made up of three parts: 'file path', 'pattern', and 'replacement string'. These are separated by the 'version_update_changes_separator' value. The 'file path' must _always_ either be relative to the repository root directory or absolute. The 'pattern' should be given as a 'raw' Python string."
        required: false
        type: string
        default: ""
      version_update_changes_separator:
        description: "The separator to use for 'version_update_changes' when splitting the three parts of each string."
        required: false
        type: string
        default: ","
      build_libs:
        description: "A space-separated list of packages to install via PyPI (`pip install`)."
        required: false
        type: string
        default: ""
      build_cmd:
        description: "The package build command, e.g., `'flit build'` or `'python -m build'`."
        required: false
        type: string
        default: "python -m build --outdir dist ."
      build_dir:
        description: "The directory where the built distribution is located. This should reflect the directory used in the build command or by default by the build library."
        required: false
        type: string
        default: "dist"
      tag_message_file:
        description: "Relative path to a release tag message file from the root of the repository. Example: `'.github/utils/release_tag_msg.txt'`."
        required: false
        type: string
        default: ""
      changelog_exclude_tags_regex:
        description: "A regular expression matching any tags that should be excluded from the CHANGELOG.md."
        required: false
        type: string
        default: ""
      changelog_exclude_labels:
        description: "Comma-separated list of labels to exclude from the CHANGELOG.md."
        required: false
        type: string
        default: ""
      upload_distribution:
        description: "Whether or not to upload the built distribution as an artifact. **Note**: This is only relevant if 'python_package' is 'true', which is the default."
        required: false
        type: boolean
        default: true

      # Build and release documentation
      update_docs:
        description: "Whether or not to also run the 'docs' workflow job."
        required: false
        type: boolean
        default: false
      python_version_docs:
        description: "The Python version to use for the workflow when building the documentation."
        required: false
        type: string
        default: "3.9"
      doc_extras:
        description: "Any extras to install from the local repository through 'pip'. Must be encapsulated in square parentheses (`[]`) and be separated by commas (`,`) without any spaces. Note, if this is empty, 'install_extras' will be used as a fallback. Example: `'[docs]'`."
        required: false
        type: string
        default: ""
      docs_framework:
        description: "The documentation framework to use. This can only be either `'mkdocs'` or `'sphinx'`. Defaults to `'mkdocs'`."
        required: false
        type: string
        default: "mkdocs"

      # MkDocs
      mkdocs_update_latest:
        description: "Whether or not to update the 'latest' alias to point to `release_branch`. Defaults to 'true'."
        required: false
        type: boolean
        default: true

      # Sphinx
      sphinx-build_options:
        description: "Single (space-separated) or multi-line string of command-line options to use when calling `sphinx-build`."
        required: false
        type: string
        default: ""
      docs_folder:
        description: "The path to the root documentation folder relative to the repository root. Defaults to 'docs'."
        required: false
        type: string
        default: "docs"
      build_target_folder:
        description: "The path to the target folder for the documentation build relative to the repository root. Defaults to 'site'."
        required: false
        type: string
        default: "site"

    secrets:
      PyPI_token:
        description: "A PyPI token for publishing the built package to PyPI. **Important**: This is _required_ if both 'python_package' and 'publish_on_pypi' are 'true'. Both are 'true' by default."
        required: false
      PAT:
        description: "A personal access token (PAT) with rights to update the `release_branch`. This will fallback on `GITHUB_TOKEN`."
        required: false

jobs:
  update-and-publish:
    name: Update CHANGELOG and version and publish to PyPI
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ${{ inputs.runner }}

    steps:
    - name: Validate inputs
      run: |
        if [[ ! "${{ inputs.python_version_build }}" =~ ^3\.([8-9]|1[0-4])(\..*)?$ ]]; then
          echo "Python version '${{ inputs.python_version_build }}' is not supported."
          echo "Supported versions are: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14."
          exit 1
        fi

    - name: Checkout ${{ github.repository }}
      uses: actions/checkout@v6
      with:
        fetch-depth: 0
        token: ${{ secrets.PAT || secrets.GITHUB_TOKEN }}

    - name: Set up Python ${{ inputs.python_version_build }}
      uses: actions/setup-python@v6
      with:
        python-version: "${{ inputs.python_version_build }}"
        allow-prereleases: true

    - name: Install system dependencies
      if: inputs.system_dependencies != ''
      run: |
        if [[ "${{ inputs.system_dependencies }}" =~ \n ]]; then
          # Expected to be a multi-line string
          SYSTEM_PACKAGES=()
          while IFS= read -r line; do
            if [ -n "${line}" ]; then SYSTEM_PACKAGES+=("${line}"); fi
          done <<< "${{ inputs.system_dependencies }}"
        else
          # Expected to be a single-line string
          SYSTEM_PACKAGES=(${{ inputs.system_dependencies }})
        fi

        sudo apt update && sudo apt install -y "${SYSTEM_PACKAGES[@]}"

    - name: Install Python dependencies
      run: |
        EDITABLE=
        if [ "${{ inputs.relative }}" == "true" ]; then EDITABLE=-e ; fi

        python -m pip install -U pip
        pip install -U setuptools wheel build
        pip install ${EDITABLE}.${{ inputs.install_extras }}
        if [ -n "${{ inputs.build_libs }}" ]; then
          pip install ${{ inputs.build_libs }}
        fi
        pip install git+https://github.com/SINTEF/ci-cd.git@v2.10.0
      env:
        PIP_INDEX_URL: ${{ inputs.pip_index_url }}
        PIP_EXTRA_INDEX_URL: ${{ inputs.pip_extra_index_urls }}

    - name: Parse changelog configuration
      id: changelog_config
      run: |
        if [ -n "${{ inputs.changelog_exclude_tags_regex }}" ]; then
          echo 'changelog_exclude_tags_regex=--exclude-tags-regex "${{ inputs.changelog_exclude_tags_regex }}"' >> $GITHUB_OUTPUT
        else
          echo 'changelog_exclude_tags_regex=' >> $GITHUB_OUTPUT
        fi

        if [ -n "${{ inputs.changelog_exclude_labels }}" ]; then
          echo 'changelog_exclude_labels=--exclude-labels "${{ inputs.changelog_exclude_labels }}"' >> $GITHUB_OUTPUT
        else
          echo 'changelog_exclude_labels=' >> $GITHUB_OUTPUT
        fi

        PROJECT=$(echo $GITHUB_REPOSITORY | cut -d/ -f2- )
        echo "changelog_project=--project ${PROJECT}" >> $GITHUB_OUTPUT

    - name: Update changelog
      uses: docker://githubchangeloggenerator/github-changelog-generator:1.16.2
      with:
        args: --user "${{ github.repository_owner }}" ${{ steps.changelog_config.outputs.changelog_project }} --token "${{ secrets.PAT || secrets.GITHUB_TOKEN }}" --release-branch "${{ inputs.release_branch }}" ${{ steps.changelog_config.outputs.changelog_exclude_tags_regex }} ${{ steps.changelog_config.outputs.changelog_exclude_labels }}

    - name: Set up git user
      run: |
        git config --global user.name "${{ inputs.git_username }}"
        git config --global user.email "${{ inputs.git_email }}"

    - name: Update version and tag
      run: |
        REF=${GITHUB_REF#refs/tags/}

        if [ "${{ inputs.python_package }}" == "true" ]; then
          if [ -z "${{ inputs.package_dirs }}" ]; then
            echo "package_dirs MUST be supplied, since python_package was set to 'true'."
            exit 1
          fi

          DEBUG=
          if [ "${{ inputs.test }}" == "true" ]; then DEBUG=--test; fi

          PACKAGE_DIRS=()
          CODE_BASE_UPDATES=()
          while IFS= read -r line; do
            if [ -n "${line}" ]; then PACKAGE_DIRS+=(${line}); fi
          done <<< "${{ inputs.package_dirs }}"
          while IFS= read -r line; do
            if [ -n "${line}" ]; then CODE_BASE_UPDATES+=(--code-base-update="${line}"); fi
          done <<< "${{ inputs.version_update_changes }}"

          for package_dir in ${PACKAGE_DIRS}; do
            ci-cd setver ${DEBUG} \
              --version="${REF}" \
              --root-repo-path="${PWD}" \
              --package-dir="${package_dir}" \
              --code-base-update-separator="${{ inputs.version_update_changes_separator }}" \
              "${CODE_BASE_UPDATES[@]}"
          done
        fi

        git add -- .
        git commit -m "Release ${REF} - Changelog"

        if [ -z "${{ inputs.tag_message_file }}" ] || [ ! -f "${{ inputs.tag_message_file }}" ]; then
          TAG_MSG_FILE=.tmp_tag-msg_${{ github.run_id }}_${{ github.run_number }}_${{ github.run_attempt }}.txt

          echo -e "TAG_NAME\n\nThe full release changelog can be seen in the\n[repository source file](https://github.com/${{ github.repository }}/blob/TAG_NAME/CHANGELOG.md)." > ${TAG_MSG_FILE}
          echo "Using default release tag message."
          REMOVE_TAG_MSG_FILE=true
        else
          echo "Using found release tag message text file at ${{ inputs.tag_message_file }}."
          TAG_MSG_FILE=${{ inputs.tag_message_file }}
          REMOVE_TAG_MSG_FILE=false
        fi

        sed -i "s|TAG_NAME|${REF}|" "${TAG_MSG_FILE}"
        git tag -af -F "${TAG_MSG_FILE}" ${REF}

        if [ "${REMOVE_TAG_MSG_FILE}" == "true" ]; then rm -f "${TAG_MSG_FILE}"; fi

        if [ "${{ inputs.test }}" == "true" ]; then echo "Implemented changes in new commit:" && git diff HEAD~1; fi

    - name: Build source distribution
      run: |
        # First, clean the git tree
        git checkout -- .
        ${{ inputs.build_cmd }}

    - name: Update '${{ inputs.release_branch }}'
      uses: CasperWA/push-protected@v2
      with:
        token: ${{ secrets.PAT || secrets.GITHUB_TOKEN }}
        branch: ${{ inputs.release_branch }}
        pre_sleep: 15
        force: true
        tags: true
        unprotect_reviews: true
        debug: ${{ inputs.test }}

    - name: Get tagged versions
      id: tagged_versions
      run: |
        if [ -n "${{ inputs.changelog_exclude_tags_regex }}" ]; then
          PREVIOUS_VERSION="$(git tag -l --sort -version:refname | grep -v -E "${{ inputs.changelog_exclude_tags_regex }}" | sed -n 2p)"
        else
          PREVIOUS_VERSION="$(git tag -l --sort -version:refname | sed -n 2p)"
        fi

        if [ -n "${PREVIOUS_VERSION}" ]; then
          SINCE_PREVIOUS_VERSION="--since-tag="${PREVIOUS_VERSION}""
        else
          SINCE_PREVIOUS_VERSION=
        fi
        echo "since_previous_version=${SINCE_PREVIOUS_VERSION}" >> $GITHUB_OUTPUT

    - name: Create release-specific changelog
      uses: docker://githubchangeloggenerator/github-changelog-generator:1.16.2
      with:
        args: --user "${{ github.repository_owner }}" ${{ steps.changelog_config.outputs.changelog_project }} --token "${{ secrets.PAT || secrets.GITHUB_TOKEN }}" --release-branch "${{ inputs.release_branch }}" ${{ steps.tagged_versions.outputs.since_previous_version }} --output release_changelog.md --usernames-as-github-logins ${{ steps.changelog_config.outputs.changelog_exclude_tags_regex }} ${{ steps.changelog_config.outputs.changelog_exclude_labels }}

    - name: Append changelog to release body
      run: |
        gh api /repos/${{ github.repository }}/releases/${{ github.event.release.id }} --jq '.body' > release_body.md
        cat release_changelog.md >> release_body.md
        gh api /repos/${{ github.repository }}/releases/${{ github.event.release.id }} -X PATCH -F body='@release_body.md'
      env:
        GITHUB_TOKEN: ${{ secrets.PAT || secrets.GITHUB_TOKEN }}

    - name: Upload source distribution
      if: inputs.upload_distribution && inputs.python_package
      uses: actions/upload-artifact@v7
      with:
        name: dist
        path: ${{ inputs.build_dir }}
        if-no-files-found: error
        overwrite: true

    - name: Publish package to TestPyPI
      if: inputs.test && inputs.publish_on_pypi && inputs.python_package
      uses: pypa/gh-action-pypi-publish@release/v1
      with:
        user: __token__
        password: ${{ secrets.PyPI_token }}
        repository-url: https://test.pypi.org/legacy/
        packages-dir: ${{ inputs.build_dir }}

    - name: Publish package to PyPI
      if: ( ! inputs.test ) && inputs.publish_on_pypi && inputs.python_package
      uses: pypa/gh-action-pypi-publish@release/v1
      with:
        user: __token__
        password: ${{ secrets.PyPI_token }}
        packages-dir: ${{ inputs.build_dir }}

  docs:
    name: Deploy release documentation
    needs: update-and-publish
    runs-on: ${{ inputs.runner }}
    if: inputs.update_docs

    permissions:
      contents: write

    steps:
    - name: Check input
      run: |
        valid_frameworks=("mkdocs sphinx")
        if [[ ! " ${valid_frameworks[*]} " =~ " ${{ inputs.docs_framework }} " ]]; then
            echo "The input '${{ inputs.docs_framework }}' is not supported."
            echo "Valid inputs are: ${valid_frameworks[*]}"
            exit 1
        fi

    - name: Checkout ${{ github.repository }}
      uses: actions/checkout@v6
      with:
        fetch-depth: 0
        ref: ${{ inputs.release_branch }}

    - name: Set up Python ${{ inputs.python_version_docs }}
      uses: actions/setup-python@v6
      with:
        python-version: "${{ inputs.python_version_docs }}"
        allow-prereleases: true

    - name: Install system dependencies
      if: inputs.system_dependencies != ''
      run: |
        if [[ "${{ inputs.system_dependencies }}" =~ \n ]]; then
          # Expected to be a multi-line string
          SYSTEM_PACKAGES=()
          while IFS= read -r line; do
            if [ -n "${line}" ]; then SYSTEM_PACKAGES+=("${line}"); fi
          done <<< "${{ inputs.system_dependencies }}"
        else
          # Expected to be a single-line string
          SYSTEM_PACKAGES=(${{ inputs.system_dependencies }})
        fi

        sudo apt update && sudo apt install -y "${SYSTEM_PACKAGES[@]}"

    - name: Install Python dependencies
      run: |
        EDITABLE=
        if [ "${{ inputs.relative }}" == "true" ]; then EDITABLE=-e ; fi

        python -m pip install -U pip
        pip install -U setuptools wheel
        pip install ${EDITABLE}.${{ inputs.doc_extras || inputs.install_extras }}

        INSTALLED_PACKAGES=$(pip freeze)
        if [ "${{ inputs.docs_framework }}" == "mkdocs" ]; then
          if [[ ! $(echo -e "${INSTALLED_PACKAGES}" | grep -ciE '(mkdocs|mike)==') -eq 2 ]]; then
            echo "Missing one or more of the following packages: mkdocs, mike"
            exit 1
          fi
        elif [ "${{ inputs.docs_framework }}" == "sphinx" ]; then
          if [[ ! $(echo -e "${INSTALLED_PACKAGES}" | grep -ci 'sphinx==') -eq 1 ]]; then
            echo "Missing one or more of the following packages: sphinx"
            exit 1
          fi
        else
          echo "Unknown framework: ${{ inputs.docs_framework }}"
          exit 1
        fi
      env:
        PIP_INDEX_URL: ${{ inputs.pip_index_url }}
        PIP_EXTRA_INDEX_URL: ${{ inputs.pip_extra_index_urls }}

    - name: Set up git user
      run: |
        git config --global user.name "${{ inputs.git_username }}"
        git config --global user.email "${{ inputs.git_email }}"

    - name: Build (& deploy MkDocs) documentation
      run: |
        REF=${GITHUB_REF#refs/tags/}

        if [ "${{ inputs.docs_framework }}" == "sphinx" ]; then
          if [[ "${{ inputs.sphinx-build_options }}" =~ \n ]]; then
            # Expected to be a multi-line string
            SPHINX_OPTIONS=()
            while IFS= read -r line; do
              if [ -n "${line}" ]; then SPHINX_OPTIONS+=("${line}"); fi
            done <<< "${{ inputs.sphinx-build_options }}"
          else
            # Expected to be a single-line string
            SPHINX_OPTIONS=(${{ inputs.sphinx-build_options }})
          fi
        fi

        if [ "${{ inputs.test }}" == "true" ]; then
          if [ "${{ inputs.docs_framework }}" == "mkdocs" ]; then
            echo "Will here deploy documentation using 'mike': '${REF#v}' with alias 'stable'"
            echo "Release 'latest': ${{ inputs.mkdocs_update_latest }}"
            if [ "${{ inputs.mkdocs_update_latest }}" == "true" ]; then
              echo "  Another release: 'latest' with alias '${{ inputs.release_branch }}'"
            else
              echo "  No other release."
            fi
          elif [ "${{ inputs.docs_framework }}" == "sphinx" ]; then
            echo "Will here deploy documentation using 'sphinx-build'."
            echo "sphinx-build options: ${SPHINX_OPTIONS[@]}"
            echo "SOURCEDIR=${{ inputs.docs_folder }}"
            echo "OUTPUTDIR=${{ inputs.build_target_folder }}"
            echo "Then '${{ inputs.build_target_folder }}' would replace all content in the 'gh-pages' branch."
          else
            echo "Unknown framework: ${{ inputs.docs_framework }}"
            exit 1
          fi

        elif [ "${{ inputs.docs_framework }}" == "mkdocs" ]; then
          mike deploy --push --remote origin --branch gh-pages --update-aliases --config-file mkdocs.yml ${REF#v} stable
          if [ "${{ inputs.mkdocs_update_latest }}" == "true" ]; then
            mike deploy --push --remote origin --branch gh-pages --update-aliases --config-file mkdocs.yml latest ${{ inputs.release_branch }}
          fi

        elif [ "${{ inputs.docs_framework }}" == "sphinx" ]; then
          sphinx-build \
            "${SPHINX_OPTIONS[@]}" \
            ${{ inputs.docs_folder }} ${{ inputs.build_target_folder }}

        else
          echo "Unknown framework: ${{ inputs.docs_framework }}"
          exit 1
        fi

    - name: Deploy Sphinx documentation
      if: inputs.docs_framework == 'sphinx'
      uses: JamesIves/github-pages-deploy-action@v4
      with:
        folder: ${{ inputs.build_target_folder }}
        git-config-name: ${{ inputs.git_username }}
        git-config-email: ${{ inputs.git_email }}