release-impl.yml

name: ⚙️ Release

on:
  workflow_call:
    inputs:
      pre_release_branch:
        required: true
        type: string
        description: >
          Template parameter.
          Name of branch with pre-release code.
      release_branch:
        required: true
        type: string
        description: >
          Template parameter.
          Name of branch with releases.
      app_name:
        required: true
        type: string
        description: >
          Template parameter.
          Human-readable application name.
      executable_name:
        required: true
        type: string
        description: >
          Template parameter.
          Root name of executable.
      pyinstaller_dir:
        type: string
        description: >
          Template parameter.
          Name of directory containing pyinstaller configuration, hooks and support files.
        default: pyinstaller
      version_file:
        required: true
        type: string
        description: >
          Template parameter.
          Path to Python file containing application version data.
      benchmark_make_workflow:
        required: true
        type: string
        description: >
          Template parameter.
          Path to application workflow used for benchmarking purposes.
      pypi-url:
        required: true
        type: string
        description: >
          Template parameter.
          URL to PyPI to use when uploading a release.
      website_source_org:
        required: true
        type: string
        description: >
          Template parameter.
          Name of organisation owning the website to publish docs to.
      website_source_repo:
        required: true
        type: string
        description: >
          Template parameter.
          Name of repository to publish the website docs to.
      repository:
        required: true
        type: string
        description: >
          Template parameter.
          Name of organisation/repository containing the code being released.
      docs_url_prefix:
        required: true
        type: string
        description: >
          Template parameter.
          Prefix to apply to documentation URL.
      gh-run-attempt:
        required: true
        type: string
        description: >
          Attribute: `github.run_attempt`
          Which attempt at running the workflow is this?
        default: ${{ github.run_attempt }}
      pr-merged:
        required: true
        type: string
        description: >
          Attribute: `github.event.pull_request.merged`
          Is this running as the result of a PR being merged?
        default: ${{ github.event.pull_request.merged }}
      pr-title:
        required: true
        type: string
        description: >
          Attribute: `github.event.pull_request.title`
          What is the title of the PR that was merged?
        default: ${{ github.event.pull_request.title }}
      pr-base-ref:
        required: true
        type: string
        description: >
          Attribute: `github.event.pull_request.base.ref`
          Where was the PR merged into?
        default: ${{ github.event.pull_request.base.ref }}
      pr-head-ref:
        required: true
        type: string
        description: >
          Attribute: `github.event.pull_request.head.ref`
          Where was the PR merged from?
        default: ${{ github.event.pull_request.head.ref }}
      python-version:
        description: >
          Version of Python to use.
          Note that the version in Rocky Linux is locked by the Docker image.
        type: string
        required: false
        default: "3.13"
      poetry-version:
        description: >
          Version of Poetry to use.
          Note that the version in Rocky Linux is locked by the Docker image.
        type: string
        required: false
        default: "2.1.3"
      recovery-tag:
        description: >
          Existing stable release tag to publish without bumping versions or moving tags.
          Only supported for workflow_dispatch, before GitHub or PyPI publication.
        type: string
        default: ""
      recovery-previous-tag:
        description: Previous stable release tag used as the exclusive release notes boundary.
        type: string
        default: ""
    secrets:
      general-token:
        description: >
          General github token without special permissions.
        required: true
      commit-token:
        description: >
          Token for committing to the main repository.
        required: true
      pypi-token:
        description: >
          Token for publishing to PyPI.
        required: true
      website-token:
        description: >
          Token for publishing the website.
        required: true
    outputs:
      new-version:
        description: >
          The new version created.
        value: ${{ jobs.bump-version.outputs.new_tag }}
      changelog-url:
        description: >
          URL to the generated CHANGELOG.
        value: ${{ jobs.bump-version.outputs.changelog }}
      pypi-published:
        description: >
          Whether the release was successfully published to PyPI.
        value: ${{ jobs.release-github-PyPI.outputs.publish-state == 'success' }}
      website-published:
        description: >
          Whether the release was successfully published to the website.
        value: ${{ jobs.update-website.outputs.publish-state == 'success' }}

jobs:
  bump-version:
    # Recovery requires manual dispatch. Normal releases skip reruns, unmerged PRs, and unrelated merges.
    if: (inputs.recovery-tag != '' && github.event_name == 'workflow_dispatch') || (inputs.recovery-tag == '' && inputs.gh-run-attempt == '1' && inputs.pr-merged == 'true' && !contains(inputs.pr-title, '[skip release]') && (inputs.pr-base-ref == inputs.pre_release_branch || (inputs.pr-base-ref == inputs.release_branch && inputs.pr-head-ref == inputs.pre_release_branch)) && (!(github.event && github.event.pull_request) || github.event.pull_request.merged))
    runs-on: ubuntu-latest
    outputs:
      new_tag: ${{ steps.new_tag.outputs.tag }}
      version: ${{ steps.new_tag.outputs.version }}
      changelog: ${{ steps.upload-changelog.outputs.artifact-url }}
      source-ref: ${{ steps.recovery.outputs.sha }}
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0 # get all history and tags
          ref: ${{ inputs.pr-base-ref }}
          token: ${{ secrets.commit-token }}
          persist-credentials: ${{ inputs.recovery-tag == '' }}
          allow-unsafe-pr-checkout: true
      - name: Configure git
        if: inputs.recovery-tag == ''
        uses: $/configure-git
      - name: Set up python ${{ inputs.python-version }}
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ inputs.python-version }}

      - name: Set up poetry for recovery validation
        if: inputs.recovery-tag != ''
        uses: $/setup-poetry
        with:
          version: ${{ inputs.poetry-version }}

      - name: Validate unpublished stable release for recovery
        if: inputs.recovery-tag != ''
        id: recovery
        env:
          TAG: ${{ inputs.recovery-tag }}
          PREVIOUS_TAG: ${{ inputs.recovery-previous-tag }}
          BASE_BRANCH: ${{ inputs.pr-base-ref }}
          RELEASE_BRANCH: ${{ inputs.release_branch }}
          REPOSITORY: ${{ inputs.repository }}
          CALLER_REPOSITORY: ${{ github.repository }}
          PYPI_URL: ${{ inputs.pypi-url }}
          GH_TOKEN: ${{ secrets.general-token }}
          GH_API_URL: ${{ github.api_url }}
        run: |
          set -euo pipefail
          if [[ "$BASE_BRANCH" != "$RELEASE_BRANCH" || "$REPOSITORY" != "$CALLER_REPOSITORY" ]]; then
            echo "::error::Recovery must target the stable branch of the calling repository."
            exit 1
          fi
          if [[ ! "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ || ! "$PREVIOUS_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ || "$TAG" == "$PREVIOUS_TAG" ]]; then
            echo "::error::Recovery requires two different stable tags of the form vX.Y.Z."
            exit 1
          fi
          if [[ "$(printf '%s\n' "$PREVIOUS_TAG" "$TAG" | sort -V | head -n 1)" != "$PREVIOUS_TAG" ]]; then
            echo "::error::The previous stable version must be lower than the recovery version."
            exit 1
          fi
          sha=$(git rev-parse --verify "refs/tags/$TAG^{commit}")
          previous_sha=$(git rev-parse --verify "refs/tags/$PREVIOUS_TAG^{commit}")
          if [[ "$sha" == "$previous_sha" ]] || ! git merge-base --is-ancestor "$previous_sha" "$sha"; then
            echo "::error::The previous stable tag must strictly precede the recovery tag."
            exit 1
          fi
          if ! git merge-base --is-ancestor "$sha" "origin/$RELEASE_BRANCH"; then
            echo "::error::The recovery tag must be on the stable release branch."
            exit 1
          fi
          git checkout --detach "$sha"
          package_version=$(poetry version)
          read -r package version <<< "$package_version"
          if [[ "$version" != "${TAG#v}" ]]; then
            echo "::error::The package version does not match the recovery tag."
            exit 1
          fi
          case "$PYPI_URL" in
            https://upload.pypi.org/legacy/) index=https://pypi.org/pypi ;;
            https://test.pypi.org/legacy/) index=https://test.pypi.org/pypi ;;
            *) echo "::error::Recovery supports only PyPI and TestPyPI."; exit 1 ;;
          esac
          github_status=$(curl --silent --show-error --location --output /dev/null --write-out '%{http_code}' \
            --header "Authorization: Bearer $GH_TOKEN" \
            "$GH_API_URL/repos/$REPOSITORY/releases/tags/$TAG")
          pypi_status=$(curl --silent --show-error --location --output /dev/null --write-out '%{http_code}' \
            "$index/$package/$version/json")
          if [[ "$github_status" != 404 || "$pypi_status" != 404 ]]; then
            echo "::error::Recovery requires an unpublished version. GitHub HTTP: $github_status; PyPI HTTP: $pypi_status. Inspect existing publications or API errors before proceeding."
            exit 1
          fi
          echo "sha=$sha" >> "$GITHUB_OUTPUT"

      - name: Get git-chglog executable
        run: |
          wget https://github.com/git-chglog/git-chglog/releases/download/v0.15.0/git-chglog_0.15.0_linux_amd64.tar.gz
          tar --extract --file git-chglog_0.15.0_linux_amd64.tar.gz git-chglog

      - name: Install commitizen
        if: inputs.recovery-tag == ''
        run: pip install commitizen

      - name: Manipulate tags (stable release)
        if: inputs.recovery-tag == '' && inputs.pr-base-ref == inputs.release_branch
        id: pre_tag
        # delete all pre-release tags, set current version to the latest stable release,
        run: |
          CUR_PRE_TAG=$(git describe --tags $(git rev-list --tags --max-count=1))
          echo "CUR_PRE_TAG is: $CUR_PRE_TAG"
          echo "tag=$CUR_PRE_TAG" >> $GITHUB_OUTPUT
          git tag -l | awk '/^(v[0-9]+\.[0-9]+\.[0-9]+(a|b|rc).*)$/ {print $1}' | xargs git tag -d

      - name: Get current tag
        if: inputs.recovery-tag == ''
        id: cur_tag
        run: |
          CUR_TAG=$(git describe --tags $(git rev-list --tags --max-count=1))
          echo "CUR_TAG is: $CUR_TAG"
          echo "tag=$CUR_TAG" >> $GITHUB_OUTPUT

      - name: Commitizen bump (pre-release) # Bump version strings (pre-release) and add a new tag; commit
        if: inputs.recovery-tag == '' && inputs.pr-base-ref == inputs.pre_release_branch
        run: cz bump --prerelease alpha

      - name: Commitizen bump # First update version number to latest stable release, then bump to new stable release, add a new tag and commit
        if: inputs.recovery-tag == '' && inputs.pr-base-ref == inputs.release_branch
        run: |
          python3 -c '
          from commitizen.bump import update_version_in_files
          import os
          update_version_in_files(
              current_version=os.environ["pre_tag"].lstrip("v"),
              new_version=os.environ["cur_tag"].lstrip("v"),
              version_files=["pyproject.toml", os.environ["ver_file"]],
              check_consistency=False,
              encoding="utf-8",
          )'
          cz bump
        env:
          pre_tag: ${{ steps.pre_tag.outputs.tag }}
          cur_tag: ${{ steps.cur_tag.outputs.tag }}
          ver_file: ${{ inputs.version_file }}

      - name: Get new tag
        id: new_tag
        run: |
          if [[ -n "$RECOVERY_TAG" ]]; then
            NEW_TAG="$RECOVERY_TAG"
          else
            NEW_TAG=$(git describe --tags $(git rev-list --tags --max-count=1))
          fi
          echo "NEW_TAG is: $NEW_TAG"
          echo "tag=$NEW_TAG" >> $GITHUB_OUTPUT
          echo "version=${NEW_TAG:1}" >> $GITHUB_OUTPUT
        env:
          RECOVERY_TAG: ${{ inputs.recovery-tag }}

      - name: Generate CHANGELOG (stable release)
        if: inputs.recovery-tag == '' && inputs.pr-base-ref == inputs.release_branch
        run: |
          ./git-chglog --output CHANGELOG.md
          git add CHANGELOG.md

      - name: Generate CHANGELOG-dev (pre-release)
        if: inputs.recovery-tag == '' && inputs.pr-base-ref == inputs.pre_release_branch
        run: |
          ./git-chglog --output CHANGELOG-dev.md
          git add CHANGELOG-dev.md
      - name: Push new CHANGELOG
        if: inputs.recovery-tag == ''
        run: |
          git tag -d $new_tag
          git commit --amend --no-edit
          git tag $new_tag
          git push && git push origin $new_tag
        env:
          new_tag: ${{ steps.new_tag.outputs.tag }}

      - name: Sync release branch into develop branch if exists (stable release)
        if: inputs.recovery-tag == '' && inputs.pr-base-ref == inputs.release_branch
        run: |
          exists_in_remote=$(git ls-remote --heads origin "refs/heads/$PRE_BRANCH")
          echo "exists_in_remote: $exists_in_remote"
          if [[ -n $exists_in_remote ]]; then
            export SKIP=end-of-file-fixer
            # Merge rather than rebase: the pre-release branch may have gained
            # commits (e.g. from a concurrent pre-release run) that are not on
            # the release branch, and rewriting them would need a force-push.
            for attempt in 1 2 3; do
              git fetch origin "$PRE_BRANCH"
              git checkout -B "$PRE_BRANCH" "origin/$PRE_BRANCH"
              if git merge-base --is-ancestor HEAD "$BASE_BRANCH"; then
                git merge --ff-only "$BASE_BRANCH"
              else
                echo "$PRE_BRANCH has commits not on $BASE_BRANCH; merging."
                git merge --no-ff --no-edit -m "Merge branch '$BASE_BRANCH' into $PRE_BRANCH [skip ci]" "$BASE_BRANCH"
              fi
              if git push -u origin "$PRE_BRANCH"; then
                exit 0
              fi
              echo "Push of $PRE_BRANCH rejected (attempt $attempt); retrying."
              sleep 5
            done
            exit 1
          else
            echo "No $PRE_BRANCH branch to merge into."
          fi
        env:
          PRE_BRANCH: ${{ inputs.pre_release_branch }}
          BASE_BRANCH: ${{ inputs.release_branch }}

      - name: Generate incremental CHANGELOG for GitHub release body (stable release)
        if: inputs.pr-base-ref == inputs.release_branch
        run: |
          if [[ -n "$RECOVERY_TAG" ]]; then
            tag_pattern="^(${PREVIOUS_TAG//./[.]}|${RECOVERY_TAG//./[.]})$"
            ./git-chglog --tag-filter-pattern "$tag_pattern" --sort semver \
              --template .chglog/RELEASE.tpl.md --output CHANGELOG_increment.md "$RECOVERY_TAG"
          else
            ./git-chglog --template .chglog/RELEASE.tpl.md --output CHANGELOG_increment.md "$cur_tag.."
          fi
          cat CHANGELOG_increment.md
        env:
          cur_tag: ${{ steps.cur_tag.outputs.tag }}
          new_tag: ${{ steps.new_tag.outputs.tag }}
          RECOVERY_TAG: ${{ inputs.recovery-tag }}
          PREVIOUS_TAG: ${{ inputs.recovery-previous-tag }}

      - name: Generate incremental CHANGELOG for GitHub release body (pre-release)
        if: inputs.pr-base-ref == inputs.pre_release_branch
        run: |
          ./git-chglog --template .chglog/RELEASE.tpl.md --output CHANGELOG_increment.md "$new_tag"
          cat CHANGELOG_increment.md
        env:
          new_tag: ${{ steps.new_tag.outputs.tag }}

      - name: Store the incremental CHANGELOG
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        id: upload-changelog
        with:
          name: CHANGELOG_increment
          path: CHANGELOG_increment.md

  cache-app-data:
    needs: bump-version
    # skip if '[skip release]' is in the PR title; or if merging any branch other than pre_release_branch into release_branch
    if: "!contains(inputs.pr-title, '[skip release]') && (inputs.pr-base-ref == inputs.pre_release_branch || (inputs.pr-base-ref == inputs.release_branch && inputs.pr-head-ref == inputs.pre_release_branch)) && (!(github.event && github.event.pull_request) || github.event.pull_request.merged)"
    permissions:
      # No write permission
      contents: read
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.bump-version.outputs.source-ref || inputs.pr-base-ref }}
          allow-unsafe-pr-checkout: true
          persist-credentials: false

      - name: Set up python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ inputs.python-version }}

      - name: Set up poetry
        uses: $/setup-poetry
        with:
          version: ${{ inputs.poetry-version }}

      - name: Cache dependencies
        uses: $/init-cache
        with:
          name: test
          version: ${{ inputs.python-version }}

      - name: Install dependencies
        run: |
          poetry install --without dev,pyinstaller

      - name: Cache all app data and programs
        run: |
          poetry run "$EXE_NAME" manage cache-all
        env:
          EXE_NAME: ${{ inputs.executable_name }}
          FSSPEC_GITHUB_USERNAME: x-access-token
          FSSPEC_GITHUB_TOKEN: ${{ secrets.general-token }}

      - name: Upload all cached app data/programs
        id: upload-cached-app-data
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: ${{ inputs.executable_name }}-app-data-cache
          path: ~/.cache/${{ inputs.executable_name }}
          retention-days: 1

  build-executables:
    needs: [bump-version, cache-app-data]
    strategy:
      fail-fast: false
      matrix:
        os: [windows-latest, macos-latest]
        include:
          - os: windows-latest
            executable_ext: .exe
            executable_os: win
          - os: macos-latest
            executable_ext: ""
            executable_os: macOS

    runs-on: ${{ matrix.os }}
    env:
      BUILT_EXE_BASE_NAME: ${{ inputs.executable_name }}-${{ needs.bump-version.outputs.new_tag }}
      BUILT_EXE_PATH_DIR: ${{ inputs.pyinstaller_dir }}/dist/onedir/${{ inputs.executable_name }}-${{ needs.bump-version.outputs.new_tag }}-${{ matrix.executable_os }}-dir/${{ inputs.executable_name }}-${{ needs.bump-version.outputs.new_tag }}-${{ matrix.executable_os }}-dir${{ matrix.executable_ext }}
      BUILT_EXE_PATH_DIR_ZIPPED: ${{ inputs.pyinstaller_dir }}/dist/onedir/${{ inputs.executable_name }}-${{ needs.bump-version.outputs.new_tag }}-${{ matrix.executable_os }}-dir.zip
      BUILT_EXE_PATH_FILE: ${{ inputs.pyinstaller_dir }}/dist/onefile/${{ inputs.executable_name }}-${{ needs.bump-version.outputs.new_tag }}-${{ matrix.executable_os }}${{ matrix.executable_ext }}
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.bump-version.outputs.source-ref || inputs.pr-base-ref }} # use the validated commit during recovery
          allow-unsafe-pr-checkout: true
          persist-credentials: false
      - name: Set up python ${{ inputs.python-version }}
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ inputs.python-version }}
      - name: Cache dependencies
        uses: $/init-cache
        with:
          name: build
          version: ${{ inputs.python-version }}

      - name: Download prepared cached app data
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: ${{ inputs.executable_name }}-app-data-cache
          path: ${{ inputs.executable_name }}-app-data-cache

      - name: Set up poetry
        uses: $/setup-poetry
        with:
          version: ${{ inputs.poetry-version }}

      - name: Install dependencies
        run: poetry install --without dev

      - name: Install cached app data
        env:
          PYTHONUTF8: 1
          EXE_NAME: ${{ inputs.executable_name }}
        run: |
          poetry run "$EXE_NAME" data install-cache "${EXE_NAME}-app-data-cache/data"
          poetry run "$EXE_NAME" data --list
          poetry run "$EXE_NAME" program install-cache "${EXE_NAME}-app-data-cache/programs"
          poetry run "$EXE_NAME" program --list
        shell: bash

      - name: Build with pyinstaller (non-Windows, file)
        if: runner.os != 'Windows'
        working-directory: ${{ inputs.pyinstaller_dir }}
        run: ./make.sh $TARGET INFO 'onefile'
        env:
          TARGET: ${{ env.BUILT_EXE_BASE_NAME }}-${{ matrix.executable_os }}

      - name: Build with pyinstaller (non-Windows, folder)
        if: runner.os != 'Windows'
        working-directory: ${{ inputs.pyinstaller_dir }}
        run: ./make.sh $TARGET INFO 'onedir'
        env:
          TARGET: ${{ env.BUILT_EXE_BASE_NAME }}-${{ matrix.executable_os }}-dir

      - name: Build with pyinstaller (Windows, file)
        if: runner.os == 'Windows'
        working-directory: ${{ inputs.pyinstaller_dir }}
        run: ./make.ps1 -ExeName $Env:TARGET -LogLevel INFO -BuildType 'onefile'
        env:
          TARGET: ${{ env.BUILT_EXE_BASE_NAME }}-${{ matrix.executable_os }}

      - name: Build with pyinstaller (Windows, folder)
        if: runner.os == 'Windows'
        working-directory: ${{ inputs.pyinstaller_dir }}
        run: ./make.ps1 -ExeName $Env:TARGET -LogLevel INFO -BuildType 'onedir'
        env:
          TARGET: ${{ env.BUILT_EXE_BASE_NAME }}-${{ matrix.executable_os }}-dir

      - name: Version check (file)
        if: runner.os != 'Windows'
        uses: $/compare
        with:
          expected: "${{ inputs.app_name }}, version ${{ needs.bump-version.outputs.version }}"
          command: |
            "$BUILT_EXE_PATH_FILE" --version

      - name: Version check (folder)
        if: runner.os != 'Windows'
        uses: $/compare
        with:
          expected: "${{ inputs.app_name }}, version ${{ needs.bump-version.outputs.version }}"
          command: |
            "$BUILT_EXE_PATH_DIR" --version

      - name: Version check (file)
        if: runner.os == 'Windows'
        uses: $/compare
        with:
          expected: "${{ inputs.app_name }}, version ${{ needs.bump-version.outputs.version }}"
          command: |
            "$Env:BUILT_EXE_PATH_FILE" --version

      - name: Version check (folder)
        if: runner.os == 'Windows'
        uses: $/compare
        with:
          expected: "${{ inputs.app_name }}, version ${{ needs.bump-version.outputs.version }}"
          command: |
            "$Env:BUILT_EXE_PATH_DIR" --version

      - name: Run test suite on the frozen app (windows, folder)
        if: runner.os == 'Windows'
        env:
          GH_TOKEN: ${{ secrets.general-token }}
        run: |
          & "$Env:BUILT_EXE_PATH_DIR" test

      - name: Run test suite on the frozen app (non-windows, folder)
        if: runner.os != 'Windows'
        env:
          GH_TOKEN: ${{ secrets.general-token }}
        run: |
          "$BUILT_EXE_PATH_DIR" test

      - name: Compress folder (windows, folder)
        if: runner.os == 'Windows'
        working-directory: ${{ inputs.pyinstaller_dir }}
        run: ./compress.ps1 -ExeName "$env:TARGET" -BuildType 'onedir'
        env:
          TARGET: ${{ env.BUILT_EXE_BASE_NAME }}-${{ matrix.executable_os }}-dir

      - name: Compress folder (non-windows, folder)
        if: runner.os != 'Windows'
        working-directory: ${{ inputs.pyinstaller_dir }}
        run: ./compress.sh $TARGET 'onedir'
        env:
          TARGET: ${{ env.BUILT_EXE_BASE_NAME }}-${{ matrix.executable_os }}-dir

      - name: Upload executable artifact (file)
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: ${{ env.BUILT_EXE_BASE_NAME }}-${{ matrix.executable_os }}${{ matrix.executable_ext }}
          path: ${{ env.BUILT_EXE_PATH_FILE }}
          retention-days: 7

      - name: Upload executable artifact (compressed folder)
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: ${{ env.BUILT_EXE_BASE_NAME }}-${{ matrix.executable_os }}-dir.zip
          path: ${{ env.BUILT_EXE_PATH_DIR_ZIPPED }}
          retention-days: 7

  build-executables-linux:
    runs-on: ubuntu-latest
    needs: [bump-version, cache-app-data]
    env:
      BUILT_EXE_BASE_NAME: ${{ inputs.executable_name }}-${{ needs.bump-version.outputs.new_tag }}
      BUILT_EXE_PATH_DIR: ${{ inputs.pyinstaller_dir }}/dist/onedir/${{ inputs.executable_name }}-${{ needs.bump-version.outputs.new_tag }}-linux-dir/${{ inputs.executable_name }}-${{ needs.bump-version.outputs.new_tag }}-linux-dir
      BUILT_EXE_PATH_DIR_ZIPPED: ${{ inputs.pyinstaller_dir }}/dist/onedir/${{ inputs.executable_name }}-${{ needs.bump-version.outputs.new_tag }}-linux-dir.zip
      BUILT_EXE_PATH_FILE: ${{ inputs.pyinstaller_dir }}/dist/onefile/${{ inputs.executable_name }}-${{ needs.bump-version.outputs.new_tag }}-linux
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.bump-version.outputs.source-ref || inputs.pr-base-ref }} # use the validated commit during recovery
          allow-unsafe-pr-checkout: true
          persist-credentials: false
      - name: Cache dependencies
        uses: $/init-cache
        with:
          name: build
          version: ${{ inputs.python-version }}

      - name: Download prepared cached app data
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: ${{ inputs.executable_name }}-app-data-cache
          path: ${{ inputs.executable_name }}-app-data-cache

      - name: Build executables within Docker
        uses: $/run-in-docker
        with:
          options: |
            -v ${{ github.workspace }}:/home
            --env GH_TOKEN
            --env BUILT_EXE_PATH_FILE
            --env EXE_NAME
            --env PYINST_DIR
            --env BUILT_EXE_BASE_NAME
            --env BUILT_EXE_PATH_DIR
            --env EXPECTED
          run: |
            vers_expected="$EXPECTED"

            # set up poetry
            cd /home
            poetry config virtualenvs.in-project true
            poetry install --without dev

            # build with pyinstaller for Rocky Linux (file)
            cd "$PYINST_DIR"
            ./make.sh "${BUILT_EXE_BASE_NAME}-linux" INFO onefile
            cd ..

            # version check (file)
            vers=$("$BUILT_EXE_PATH_FILE" --version)
            echo $vers
            echo $vers_expected
            [ "$vers" = "$vers_expected" ]

            # install cache data
            "$BUILT_EXE_PATH_FILE" data install-cache "${EXE_NAME}-app-data-cache/data"
            "$BUILT_EXE_PATH_FILE" data --list
            "$BUILT_EXE_PATH_FILE" program install-cache "${EXE_NAME}-app-data-cache/programs"
            "$BUILT_EXE_PATH_FILE" program --list

            # run test suite on the frozen app (file)
            "$BUILT_EXE_PATH_FILE" test

            # build with pyinstaller for Rocky Linux (folder)
            cd "$PYINST_DIR"
            ./make.sh "${BUILT_EXE_BASE_NAME}-linux-dir" INFO onedir
            cd ..

            # version check (folder)
            vers=$("$BUILT_EXE_PATH_DIR" --version)
            echo $vers
            echo $vers_expected
            [ "$vers" = "$vers_expected" ]

            # run test suite on the frozen app (folder)
            "$BUILT_EXE_PATH_DIR" test

            # Compress folder (folder)
            cd "$PYINST_DIR"
            ./compress.sh "${BUILT_EXE_BASE_NAME}-linux-dir" 'onedir'
            cd ..
        env:
          GH_TOKEN: ${{ secrets.general-token }}
          EXE_NAME: ${{ inputs.executable_name }}
          PYINST_DIR: ${{ inputs.pyinstaller_dir }}
          EXPECTED: "${{ inputs.app_name }}, version ${{ needs.bump-version.outputs.version }}"

      - name: Upload executable artifact (file)
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: ${{ env.BUILT_EXE_BASE_NAME }}-linux
          path: ${{ env.BUILT_EXE_PATH_FILE }}
          retention-days: 7

      - name: Upload executable artifact (compressed folder)
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: ${{ env.BUILT_EXE_BASE_NAME }}-linux-dir.zip
          path: ${{ inputs.pyinstaller_dir }}/dist/onedir/${{ env.BUILT_EXE_BASE_NAME }}-linux-dir.zip
          retention-days: 7

  make-workflow-benchmark:
    needs: bump-version
    strategy:
      fail-fast: false
      matrix:
        python-version:
          - ${{ inputs.python-version }}
        os:
          - ubuntu-latest
          - macos-latest
          - windows-latest
        num_elements:
          - 1
          - 100
          - 10000
    runs-on: ${{ matrix.os }}
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.bump-version.outputs.source-ref || github.ref }}
          allow-unsafe-pr-checkout: true
          persist-credentials: false
      - name: Set up python ${{ inputs.python-version }}
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ matrix.python-version }}
      - name: Set up poetry
        uses: $/setup-poetry
        with:
          version: ${{ inputs.poetry-version }}
      - name: Cache dependencies
        uses: $/init-cache
        with:
          name: benchmark
          version: ${{ matrix.python-version }}

      - name: Install dependencies
        run: |
          poetry install --without dev,pyinstaller

      - name: Run app make workflow command
        run: |
          poetry run "$EXE_NAME" --timeit-file "benchmark_make_workflow_${N_ELEM}_elements-${RUNNER_OS}-py-${PY_VER}.txt" make "$BENCHMARK" --var N "$N_ELEM"
        env:
          BENCHMARK: ${{ inputs.benchmark_make_workflow }}
          EXE_NAME: ${{ inputs.executable_name }}
          PY_VER: ${{ matrix.python-version }}
          N_ELEM: ${{ matrix.num_elements }}
        shell: bash

      - name: Store benchmark data
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: benchmark_make_workflow_${{ matrix.num_elements }}_elements-${{ runner.os }}-py-${{ matrix.python-version }}.txt
          path: benchmark_make_workflow_${{ matrix.num_elements }}_elements-${{ runner.os }}-py-${{ matrix.python-version }}.txt
          retention-days: 1

  cleanup-cache:
    needs:
      - build-executables
      - build-executables-linux
    runs-on: ubuntu-latest
    steps:
      - name: Delete cache artifact
        uses: geekyeggo/delete-artifact@176a747ab7e287e3ff4787bf8a148716375ca118 # v6.0.0
        with:
          name: "*-app-data-cache"
          failOnError: false

  make-workflow-benchmark-upload:
    needs:
      - bump-version
      - make-workflow-benchmark
      - cleanup-cache
    runs-on: ubuntu-latest
    outputs:
      benchmark-url: ${{ steps.upload.outputs.artifact-url }}
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.bump-version.outputs.source-ref || github.ref }}
          allow-unsafe-pr-checkout: true
          persist-credentials: false
      - name: Make benchmark directory
        run: |
          mkdir benchmarks
      - name: Load benchmark data
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          merge-multiple: true
          path: benchmarks
      - name: zip benchmark results
        run: |
          zip -r ./benchmarks.zip benchmarks
      - name: Store compound benchmark data
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: benchmarks.zip
          path: benchmarks.zip
        id: upload

  release-github-PyPI:
    needs:
      - bump-version
      - build-executables
      - build-executables-linux
      - make-workflow-benchmark-upload
    runs-on: ubuntu-latest
    outputs:
      binary_download_links: ${{ steps.get_binary_download_links.outputs.binary_download_links }}
      release-state: ${{ steps.release.outcome }}
      publish-state: ${{ steps.publish.outcome }}
    permissions:
      contents: write
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.bump-version.outputs.source-ref || inputs.pr-base-ref }} # use the validated commit during recovery
          allow-unsafe-pr-checkout: true
          persist-credentials: false
      - name: Set up python ${{ inputs.python-version }}
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ inputs.python-version }}
      - name: Cache dependencies
        uses: $/init-cache
        with:
          name: release
          version: ${{ inputs.python-version }}
      - name: Set up poetry
        uses: $/setup-poetry
        with:
          version: ${{ inputs.poetry-version }}

      - name: Install dependencies
        run: poetry install --without dev,pyinstaller

      - name: Build (for PyPI)
        run: poetry build

      - name: Make release artifact directory
        run: mkdir release-artifacts

      - name: Download release artifacts
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          path: release-artifacts

      - name: Display structure of downloaded files
        run: ls -R

      - name: Release
        id: release
        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
        with:
          body_path: release-artifacts/CHANGELOG_increment/CHANGELOG_increment.md
          tag_name: ${{ needs.bump-version.outputs.new_tag }}
          files: |
            **/${{ inputs.executable_name }}-${{ needs.bump-version.outputs.new_tag }}-win.exe
            **/${{ inputs.executable_name }}-${{ needs.bump-version.outputs.new_tag }}-macOS
            **/${{ inputs.executable_name }}-${{ needs.bump-version.outputs.new_tag }}-linux
            **/${{ inputs.executable_name }}-${{ needs.bump-version.outputs.new_tag }}-win-dir.zip
            **/${{ inputs.executable_name }}-${{ needs.bump-version.outputs.new_tag }}-macOS-dir.zip
            **/${{ inputs.executable_name }}-${{ needs.bump-version.outputs.new_tag }}-linux-dir.zip
            **/benchmarks.zip
          prerelease: ${{ inputs.pr-base-ref == inputs.pre_release_branch }}

      - name: Release info
        id: get_binary_download_links
        shell: python
        run: |
          import os
          import string
          import random
          exe_base = os.environ['EXE_BASE']
          url_base = os.environ['URL_BASE']
          eof = ''.join(random.choices(string.ascii_uppercase + string.digits, k=24))
          with open(os.environ['GITHUB_OUTPUT'], 'a') as f:
            f.write(f'binary_download_links<<{eof}\n')
            for suffix in ['win.exe', 'macOS', 'linux', 'win-dir.zip', 'macOS-dir.zip', 'linux-dir.zip']:
              f.write(f'{exe_base}{suffix}: {url_base}{exe_base}{suffix}\n')
            f.write(f'{eof}\n')
        env:
          EXE_BASE: ${{ inputs.executable_name }}-${{ needs.bump-version.outputs.new_tag }}-
          URL_BASE: https://github.com/${{ inputs.repository }}/releases/download/${{ needs.bump-version.outputs.new_tag }}/

      - name: Publish (to ${{ inputs.pypi-url }})
        id: publish
        run: |
          poetry config repositories.pypi "$URL"
          poetry config pypi-token.pypi "$TOKEN"
          poetry publish --repository pypi
        env:
          URL: ${{ inputs.pypi-url }}
          TOKEN: ${{ secrets.pypi-token }}

  build-documentation:
    needs: [bump-version, release-github-PyPI]
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0 # get all history and tags
          ref: ${{ needs.bump-version.outputs.source-ref || inputs.pr-base-ref }} # use the validated commit during recovery
          token: ${{ secrets.commit-token }}
          persist-credentials: ${{ inputs.recovery-tag == '' }}
          allow-unsafe-pr-checkout: true

      - name: Configure git
        uses: $/configure-git

      - name: Set up python ${{ inputs.python-version }}
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ inputs.python-version }}

      - name: Write binary links YAML file and push
        run: |
          echo -e "$BIN_LINKS" > docs/source/released_binaries.yml
          if [[ -z "$RECOVERY_TAG" ]]; then
            git add .
            git commit -m "build: update binary download links file [skip ci]"
            git push
          fi
        env:
          BIN_LINKS: ${{ needs.release-github-PyPI.outputs.binary_download_links }}
          RECOVERY_TAG: ${{ inputs.recovery-tag }}

      - name: Sync release branch into develop branch if exists (stable release)
        if: inputs.recovery-tag == '' && inputs.pr-base-ref == inputs.release_branch
        run: |
          exists_in_remote=$(git ls-remote --heads origin "refs/heads/$PRE_BRANCH")
          echo "exists_in_remote: $exists_in_remote"
          if [[ -n $exists_in_remote ]]; then
            export SKIP=end-of-file-fixer
            # Merge rather than rebase: the pre-release branch may have gained
            # commits (e.g. from a concurrent pre-release run) that are not on
            # the release branch, and rewriting them would need a force-push.
            for attempt in 1 2 3; do
              git fetch origin "$PRE_BRANCH"
              git checkout -B "$PRE_BRANCH" "origin/$PRE_BRANCH"
              if git merge-base --is-ancestor HEAD "$BASE_BRANCH"; then
                git merge --ff-only "$BASE_BRANCH"
              else
                echo "$PRE_BRANCH has commits not on $BASE_BRANCH; merging."
                git merge --no-ff --no-edit -m "Merge branch '$BASE_BRANCH' into $PRE_BRANCH [skip ci]" "$BASE_BRANCH"
              fi
              if git push -u origin "$PRE_BRANCH"; then
                exit 0
              fi
              echo "Push of $PRE_BRANCH rejected (attempt $attempt); retrying."
              sleep 5
            done
            exit 1
          else
            echo "No $PRE_BRANCH branch to merge into."
          fi
        env:
          PRE_BRANCH: ${{ inputs.pre_release_branch }}
          BASE_BRANCH: ${{ inputs.release_branch }}

      - name: Cache dependencies
        uses: $/init-cache
        with:
          name: release-doc
          version: ${{ inputs.python-version }}
      - name: Set up poetry
        uses: $/setup-poetry
        with:
          version: ${{ inputs.poetry-version }}

      - name: Install dependencies
        run: poetry install --without test,pyinstaller

      - name: Build documentation with Sphinx
        run: |
          poetry run make clean
          poetry run make html
        working-directory: docs

      - name: Upload documentation artifact
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: docs_html
          path: docs/build/html

  update-website:
    needs: [bump-version, release-github-PyPI, build-documentation]
    runs-on: ubuntu-latest
    outputs:
      publish-state: ${{ steps.publish.outcome }}
    steps:
      - name: Set up python ${{ inputs.python-version }}
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ inputs.python-version }}

      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          repository: ${{ inputs.website_source_org }}/${{ inputs.website_source_repo }}
          token: ${{ secrets.website-token }}
          persist-credentials: true
          allow-unsafe-pr-checkout: true

      - name: Configure git
        uses: $/configure-git

      - name: Download documentation artifact
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: docs_html
          path: docs/${{ needs.bump-version.outputs.new_tag }}

      - name: Update stable docs symlink
        if: inputs.pr-base-ref == inputs.release_branch
        run: |
          ln -sfn "$TAG" docs/stable
        env:
          TAG: ${{ needs.bump-version.outputs.new_tag }}

      - name: Update pre-release docs symlink
        if: inputs.pr-base-ref == inputs.pre_release_branch
        run: |
          ln -sfn "$TAG" docs/dev
        env:
          TAG: ${{ needs.bump-version.outputs.new_tag }}

      - run: tree

      - name: Update doc version switcher
        run: |
          curl --fail --show-error --location "$URL" --output docs/make_vers_switcher.py
          python docs/make_vers_switcher.py "$DOC_PREFIX"
        env:
          URL: https://raw.githubusercontent.com/${{ inputs.repository }}/${{ needs.bump-version.outputs.source-ref || github.ref_name }}/docs/make_vers_switcher.py
          DOC_PREFIX: ${{ inputs.docs_url_prefix }}

      - name: Push changes
        id: publish
        run: |
          git add .
          git commit -m "update content"
          git push