changelog.yaml

---
name: Changelog & versions
"on":
  workflow_call:
  push:
    branches:
      - main
    paths:
      - changelog.md
      - "**/pyproject.toml"
      - "*requirements.txt"
      - "requirements/*.txt"
      # Trigger on any workflow change to make sure version gets hard-coded everywhere.
      - .github/workflows/*.yaml

concurrency:
  # Group workflow jobs so new commits cancels in-progress execution triggered by previous commits. Source:
  # https://mail.python.org/archives/list/pypa-committers@python.org/thread/PCBCQMJF64JGRBOX7E2EE4YLKHT4DI55/
  # https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
  cancel-in-progress: true

jobs:

  version-increments:
    # This job is not time-sensitive: do not let it to be triggered by schedule event.
    # Also skip release commits (during which bump-my-version cannot find "unreleased" string in changelog.md).
    if: github.event_name != 'schedule' && !startsWith(github.event.head_commit.message, '[changelog] Release v')
    runs-on: ubuntu-slim
    strategy:
      matrix:
        part:
          - minor
          - major
    steps:
      - uses: actions/checkout@v6.0.0
      - uses: astral-sh/setup-uv@v7.1.4
      - name: Install bump-my-version
        run: >
          uv tool install --with-requirements
          https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/bump-my-version.txt bump-my-version
      - name: ${{ matrix.part }} version bump
        # TODO: get configuration URL once https://github.com/callowayproject/bump-my-version/issues/148 is addressed,
        # so we can factorize projects' pyproject.toml files to kdeldycke/workflow/pyproject.toml .
        run: |
          bump-my-version bump --verbose ${{ matrix.part }}
      - name: Extract version
        id: get_version
        run: |
          echo "new_version=$( bump-my-version show current_version )" | tee -a "$GITHUB_OUTPUT"
      - uses: peter-evans/create-pull-request@v7.0.8
        with:
          assignees: ${{ github.actor }}
          commit-message: >
            [changelog] Bump ${{ matrix.part }} version to v${{ steps.get_version.outputs.new_version }}
          title: >
            Bump ${{ matrix.part }} version to `v${{ steps.get_version.outputs.new_version }}`
          body: >
            ### Description


            Ready to be merged into `main` branch, at the discretion of the maintainers, to bump the ${{ matrix.part }}
            part of the version number.


            ### To bump version to v${{ steps.get_version.outputs.new_version }}


            1. **click `Ready for review`** button below, to get this PR out of `Draft` mode

            1. **click `Rebase and merge`** button below


            ---


            <details><summary><code>Workflow metadata</code></summary>


            > [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
            github.run_id }}) by `${{ github.job }}` job from [`changelog.yaml`](${{ github.event.repository.html_url
            }}/blob/${{ github.sha }}/.github/workflows/changelog.yaml) workflow.


            </details>
          labels: "🆙 changelog"
          base: main
          branch: ${{ matrix.part }}-version-increment
          delete-branch: true
          draft: always-true

  prepare-release:
    # TODO: add complex time-based trigger condition to only update the changelog once a day on main branch activity to
    # keep the release date in sync.
    runs-on: ubuntu-slim
    # TODO: Use the collection of search and replace patterns from bump-my-version's TOML configuration file.
    # XXX This cannot be done because there is no way to group "replace" actions into a collection. Maybe we should
    # start to discuss this upstream.
    steps:
      - uses: actions/checkout@v6.0.0
      - uses: astral-sh/setup-uv@v7.1.4
      - name: Install bump-my-version
        run: >
          uv tool install --with-requirements
          https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/bump-my-version.txt bump-my-version
      - name: Extract version
        id: get_version
        run: |
          echo "current_version=$( bump-my-version show current_version )" | tee -a "$GITHUB_OUTPUT"
      - name: Hard-code version in workflows
        # This step is only used in the original repository to automate remote URL tagging.
        if: github.repository == 'kdeldycke/workflows'
        # XXX Default branch is set in a variable as a hack to prevent bump-my-version to modify its own invocation.
        # This hack could be removed if we manage to encode these search and replace patterns into bump-my-version's
        # TOML.
        run: >
          RELEASE_DEFAULT_BRANCH="main" &&
          bump-my-version replace --no-configured-files --ignore-missing-version
          --search "/workflows/$RELEASE_DEFAULT_BRANCH/"
          --replace "/workflows/v{current_version}/"
          ./.github/workflows/*.yaml
      - name: Set release date in changelog
        run: >
          bump-my-version replace --no-configured-files
          --search " (unreleased)"
          --replace " ({utcnow:%Y-%m-%d})"
          ./changelog.md
      - name: Update comparison URL in changelog
        run: >
          bump-my-version replace --no-configured-files
          --search "...main"
          --replace "...v{current_version}"
          ./changelog.md
      - name: Remove first warning message in changelog
        # Matches first occurrence of a multi-line important GFM alert:
        #   > [!IMPORTANT]
        #   > ...
        run: >
          bump-my-version replace --no-configured-files --ignore-missing-version
          --regex --search "^> \[\!IMPORTANT\].+?\\n\\n"
          --replace ""
          ./changelog.md
      - name: Setup Git
        run: |
          git config --global user.name "${{ github.actor }}"
          git config --global user.email "${{ github.actor }}@users.noreply.github.com"
      - name: Remove untracked directories and files
        run: |
          git clean -fd
      - name: Create release commit
        run: |
          git commit --all --message="[changelog] Release v${{ steps.get_version.outputs.current_version }}"
      - name: Re-target main branch in workflows
        # This step is only used in the original repository to automate remote URL tagging.
        if: github.repository == 'kdeldycke/workflows'
        # XXX Default branch is set in a variable as a hack to prevent bump-my-version to modify its own invocation.
        # This hack could be removed if we manage to encode these search and replace patterns into bump-my-version's
        # TOML.
        run: >
          RELEASE_DEFAULT_BRANCH="main" &&
          bump-my-version replace --no-configured-files --ignore-missing-version
          --search "/workflows/v{current_version}/"
          --replace "/workflows/$RELEASE_DEFAULT_BRANCH/"
          ./.github/workflows/*.yaml
      - name: Add new changelog entry
        run: >
          uvx
          --with-requirements https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/gha-utils.txt
          --
          gha-utils changelog ./changelog.md
      - name: Version bump
        # TODO: get configuration URL once https://github.com/callowayproject/bump-my-version/issues/148 is addressed,
        # so we can factorize projects' pyproject.toml files to kdeldycke/workflow/pyproject.toml .
        run: |
          bump-my-version bump --verbose patch
      - name: Commit post-release version bump
        run: |
          git commit --all --message="[changelog] Post-release version bump"
      - uses: peter-evans/create-pull-request@v7.0.8
        with:
          # We need custom PAT with workflows permission to hard-code version numbers in URLs in
          # .github/workflows/*.yaml files.
          token: ${{ secrets.WORKFLOW_UPDATE_GITHUB_PAT || secrets.GITHUB_TOKEN }}
          assignees: ${{ github.actor }}
          title: >
            Release `v${{ steps.get_version.outputs.current_version }}`
          body: >
            ### Description


            This PR is ready to be merged. The merge event will trigger[^1] the:


            1. creation of a `v${{ steps.get_version.outputs.current_version }}` tag on [`main`](${{
            github.event.repository.html_url }}/tree/main) branch

            1. build and release of the Python package to [PyPi](https://pypi.org)

            1. compilation of the project's binaries with Nuitka (if entry points are defined)

            1. publication of a [GitHub release](${{ github.event.repository.html_url }}/releases) with all artifacts
            above attached


            [^1]: as [defined by `release.yaml`](${{ github.event.repository.html_url }}/blob/${{
            github.sha }}/.github/workflows/release.yaml).


            ### How-to release v${{ steps.get_version.outputs.current_version }}

            1. **click `Re-run all jobs`** from the [workflow run](${{ github.event.repository.html_url
            }}/actions/runs/${{ github.run_id }}), to refresh the release date to today

            1. wait for the re-run to complete and check the result in diff view

            1. **click `Ready for review`** button below, to get this PR out of `Draft` mode

            1. **click `Rebase and merge`** button below (‼️ do not ~`Squash and merge`~: the auto-tagging job needs
            the 2 distinct commits in this PR)


            ---


            <details><summary><code>Workflow metadata</code></summary>


            > [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url
            }}/actions/runs/${{ github.run_id }}) by `${{ github.job }}` job from [`changelog.yaml`](${{
            github.event.repository.html_url }}/blob/${{ github.sha }}/.github/workflows/changelog.yaml) workflow.


            </details>
          labels: "🆙 changelog"
          base: main
          branch: prepare-release
          delete-branch: true
          draft: always-true