release.yml

# Branch-based publishing workflow.
#
# Release policy:
#   - Pushing/merging into test-release publishes the exact package version to TestPyPI.
#   - Pushing/merging into release publishes the exact package version to PyPI,
#     creates the matching git tag, and creates the GitHub Release.
#   - Pushing/merging into main is intentionally not a release trigger.
#
# Common maintainer commands:
#   git push origin main:test-release   # TestPyPI rehearsal
#   git push origin main:release        # Real PyPI release
#
# Web UI equivalent:
#   Open a PR with base=test-release or base=release and compare=main, then merge it.
#
# Trusted publishing setup:
#   Configure pending/trusted publishers on TestPyPI and PyPI with:
#     Repository: evaleval/every_eval_ever
#     Workflow: release.yml
#     Environment: testpypi  # for TestPyPI
#     Environment: pypi      # for PyPI
#
# This workflow intentionally does not use PyPI API tokens. The publish jobs request
# id-token: write only inside their protected environments, which allows PyPI's
# trusted-publishing/OIDC handshake to issue short-lived credentials.

name: Release

on:
  push:
    branches:
      - test-release
      - release

# Default to no permissions. Each job opts into only what it needs.
permissions: {}

jobs:
  build:
    name: Test and build distributions
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
    outputs:
      version: ${{ steps.version.outputs.version }}
      tag: ${{ steps.version.outputs.tag }}
      is_prerelease: ${{ steps.version.outputs.is_prerelease }}
    steps:
      - name: Checkout
        uses: actions/checkout@v6.0.2

      - name: Set up uv
        uses: astral-sh/setup-uv@v7.6.0
        with:
          enable-cache: true

      # The package version is the single source of truth for release naming.
      # Both TestPyPI and PyPI receive the exact version from pyproject.toml.
      # No CI-only version rewriting happens in this workflow.
      #
      # Release candidates are represented directly in pyproject.toml using
      # normal Python packaging / PEP 440 spelling, e.g. 0.2.0rc1. That gives:
      #   package version: 0.2.0rc1
      #   git tag:         v0.2.0rc1
      #   GitHub Release:  prerelease=true
      # Later, the final release should change pyproject.toml to 0.2.0, which
      # produces tag v0.2.0 and a non-prerelease GitHub Release.
      - name: Read package version
        id: version
        shell: bash
        run: |
          version="$(python3 - <<'PY'
          import tomllib
          with open('pyproject.toml', 'rb') as file:
              print(tomllib.load(file)['project']['version'])
          PY
          )"
          is_prerelease="$(VERSION="${version}" python3 - <<'PY'
          import os
          import re
          version = os.environ['VERSION'].lower()
          # Keep this intentionally small: we only need to decide whether the
          # GitHub Release should be marked as a prerelease. The packaging
          # backend remains responsible for validating the project version.
          # Matches common prerelease spellings such as 0.2.0a1, 0.2.0b1,
          # 0.2.0rc1, and normalized/separator variants like 0.2.0-rc1.
          print('true' if re.search(r'(^|[0-9._+-])(a|b|rc)[0-9]+($|[0-9._+-])', version) else 'false')
          PY
          )"
          echo "version=${version}" >> "$GITHUB_OUTPUT"
          echo "tag=v${version}" >> "$GITHUB_OUTPUT"
          echo "is_prerelease=${is_prerelease}" >> "$GITHUB_OUTPUT"
          echo "Package version: ${version}"
          echo "Release tag: v${version}"
          echo "GitHub prerelease: ${is_prerelease}"

      # Use uv directly and require the lockfile to match the project metadata.
      # If dependencies changed without updating the lockfile, this fails early.
      - name: Run tests
        run: uv run --locked pytest tests -v

      # Build both wheel and sdist into dist/ using the project's configured backend.
      - name: Build package
        run: uv build

      - name: Show built distributions
        run: ls -la dist

      # The publish jobs consume the exact artifacts built and tested here.
      # This keeps the trusted-publishing jobs small and avoids rebuilding in
      # jobs that have elevated OIDC publishing permissions.
      - name: Upload distributions
        uses: actions/upload-artifact@v4
        with:
          name: python-distributions
          path: dist/*
          if-no-files-found: error

  prepare-release-tag:
    name: Prepare release tag
    needs: build
    runs-on: ubuntu-latest
    permissions:
      # The release branch uses this job to push v<project.version>.
      # The test-release branch runs the same logic but uses git push --dry-run,
      # which exercises the refspec/auth path without creating a remote tag.
      contents: write
    steps:
      - name: Checkout
        uses: actions/checkout@v6.0.2
        with:
          fetch-depth: 0

      # This job is what makes the branch workflow safer than manual tagging:
      # maintainers push/merge main into release, and CI derives the tag from
      # pyproject.toml. If the tag already exists, it must point at this exact
      # commit; otherwise the workflow fails rather than moving an existing tag.
      #
      # On test-release, this creates the tag locally and dry-runs the remote
      # push. That gives confidence in the release tag logic without cluttering
      # the repository with rehearsal tags.
      - name: Create, verify, or rehearse tag
        shell: bash
        env:
          TAG: ${{ needs.build.outputs.tag }}
          BRANCH: ${{ github.ref_name }}
        run: |
          set -euo pipefail

          git fetch --force --tags origin
          git config user.name 'github-actions[bot]'
          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'

          if git rev-parse --verify --quiet "${TAG}^{commit}" >/dev/null; then
              tag_target="$(git rev-list -n 1 "${TAG}")"
              if [[ "${tag_target}" != "${GITHUB_SHA}" ]]; then
                  echo "Tag ${TAG} already exists but points at ${tag_target}, not ${GITHUB_SHA}" >&2
                  exit 1
              fi
              echo "Tag ${TAG} already points at this commit."
          else
              echo "Creating local annotated tag ${TAG} at ${GITHUB_SHA}."
              git tag -a "${TAG}" -m "${TAG}"
          fi

          if [[ "${BRANCH}" == "release" ]]; then
              echo "Pushing ${TAG} for the real release."
              git push origin "${TAG}"
          elif [[ "${BRANCH}" == "test-release" ]]; then
              echo "Dry-running ${TAG} push for TestPyPI rehearsal."
              git push --dry-run origin "${TAG}"
              echo "Dry-run complete. No remote tag was created."
          else
              echo "Unexpected branch: ${BRANCH}" >&2
              exit 1
          fi

  publish-testpypi:
    name: Publish to TestPyPI
    needs:
      - build
      - prepare-release-tag
    if: github.ref == 'refs/heads/test-release'
    runs-on: ubuntu-latest
    environment:
      name: testpypi
      url: https://test.pypi.org/p/every-eval-ever
    permissions:
      contents: read
      # Required for PyPI/TestPyPI trusted publishing. Do not replace this with
      # username/password or TWINE_* secrets.
      id-token: write
    steps:
      - name: Download distributions
        uses: actions/download-artifact@v4
        with:
          name: python-distributions
          path: dist

      # TestPyPI is a rehearsal lane. skip-existing makes repeated attempts with
      # the same version harmless, which is useful while validating publisher setup.
      - name: Publish to TestPyPI
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          repository-url: https://test.pypi.org/legacy/
          skip-existing: true

  publish-pypi:
    name: Publish to PyPI
    needs:
      - build
      - prepare-release-tag
    if: github.ref == 'refs/heads/release'
    runs-on: ubuntu-latest
    environment:
      name: pypi
      url: https://pypi.org/p/every-eval-ever
    permissions:
      contents: read
      # Required for PyPI trusted publishing. Keep this permission scoped to the
      # publishing job, not the whole workflow.
      id-token: write
    steps:
      - name: Download distributions
        uses: actions/download-artifact@v4
        with:
          name: python-distributions
          path: dist

      # Real PyPI releases should fail on duplicate versions, so skip-existing is
      # intentionally not set here.
      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1

  github-release:
    name: Create GitHub Release
    needs:
      - build
      - publish-pypi
    if: github.ref == 'refs/heads/release'
    runs-on: ubuntu-latest
    permissions:
      # Needed for gh release create.
      contents: write
    steps:
      - name: Download distributions
        uses: actions/download-artifact@v4
        with:
          name: python-distributions
          path: dist

      # Create the GitHub Release only after PyPI publish succeeds, so the GitHub
      # release page means the package is live on PyPI.
      #
      # This job intentionally does not check out the repository. Pass --repo so
      # gh knows which repository to operate on, and pass --verify-tag so the
      # release can only be created for the tag pushed by prepare-release-tag.
      #
      # If pyproject.toml contains an RC / alpha / beta version such as
      # 0.2.0rc1, the GitHub Release is marked as a prerelease automatically.
      - name: Create GitHub Release
        env:
          GH_TOKEN: ${{ github.token }}
          TAG: ${{ needs.build.outputs.tag }}
          IS_PRERELEASE: ${{ needs.build.outputs.is_prerelease }}
        shell: bash
        run: |
          set -euo pipefail
          args=(
              release create "${TAG}" dist/*
              --repo "${GITHUB_REPOSITORY}"
              --verify-tag
              --title "${TAG}"
              --generate-notes
          )
          if [[ "${IS_PRERELEASE}" == "true" ]]; then
              args+=(--prerelease)
          fi
          gh "${args[@]}"