name: Release

# Push a tag, get a release. The body always comes from CHANGELOG.md, so there is
# no second place to write release notes and therefore no second place for them to
# go stale.
#
#   git tag -a v0.4.0 -m "v0.4.0" && git push origin v0.4.0
#
# workflow_dispatch re-cuts (or updates) the release for a tag that already
# exists, since re-pushing an existing tag triggers nothing.
#
# It checks out the TAG, because the tagged code is what people install and it has
# to pass its own tests. That means it only works for tags that actually contain
# this tooling (>= v0.3.0). Tags older than that were backfilled by hand.

on:
  push:
    tags: ["v*"]
  workflow_dispatch:
    inputs:
      tag:
        description: "Existing tag to create a release for (e.g. v0.2.1)"
        required: true
        type: string

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Resolve tag
        id: tag
        run: |
          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
            echo "tag=${{ inputs.tag }}" >> "$GITHUB_OUTPUT"
          else
            echo "tag=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
          fi

      - uses: actions/checkout@v4
        with:
          ref: ${{ steps.tag.outputs.tag }}
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"

      # Never publish a release for code that does not pass its own tests. A
      # tagged commit is what people install; it has to be at least as good as
      # main.
      - name: install dev deps
        run: python -m pip install --upgrade pip pytest ruff

      - name: ruff
        run: ruff check patch tests tools

      - name: pytest
        run: pytest tests -q

      - name: shell syntax
        run: |
          fail=0
          while IFS= read -r f; do
            bash -n "$f" || { echo "::error file=$f::bash syntax error"; fail=1; }
          done < <(find . -name '*.sh' -not -path './.git/*')
          exit $fail

      # Catches the failure mode this repo actually had: VERSION= drifted to
      # three different values across the scripts, and nothing noticed.
      - name: "gate: version matches tag, CHANGELOG complete, nothing stranded"
        run: python3 tools/release_notes.py check "${{ steps.tag.outputs.tag }}"

      # THE BARRIER. A stable release must have been a release candidate on this
      # exact commit. Candidates are invisible to users (update.sh and the alert
      # source both take the newest plain vX.Y.Z), so debugging happens across
      # rc1/rc2/rc3 at no cost to anyone -- instead of across v0.5.0/v0.5.1/v0.5.2,
      # which alerts every installed box every time.
      #
      # Same code release.sh runs locally, so this should never be the first place
      # you find out. It is here because this is the only place that cannot be
      # bypassed: it holds the token that publishes.
      - name: "gate: this commit was a release candidate"
        run: python3 tools/release_gate.py "${{ steps.tag.outputs.tag }}" -C .

      # ...and the candidate has to have actually passed. Only CI can see this, so
      # it cannot live in release_gate.py with the rest.
      - name: "gate: that candidate's CI run passed"
        if: ${{ !contains(steps.tag.outputs.tag, '-rc') && !contains(steps.tag.outputs.tag, '-beta') && !contains(steps.tag.outputs.tag, '-alpha') }}
        env:
          GH_TOKEN: ${{ github.token }}
          TAG: ${{ steps.tag.outputs.tag }}
        run: |
          sha="$(git rev-list -n 1 "$TAG")"
          # Every rc tag on this exact commit -- release_gate.py already proved
          # there is at least one.
          rcs="$(git tag --points-at "$sha" | grep -E -- '-rc[0-9]+$' || true)"

          for rc in $rcs; do
            concl="$(gh run list --workflow=release.yml --branch "$rc" \
                       --json conclusion --jq '.[0].conclusion // ""' 2>/dev/null || true)"
            echo "candidate $rc -> ${concl:-<no run found>}"
            if [ "$concl" = "success" ]; then
              echo "::notice::$TAG is promoting $rc, whose release run passed."
              exit 0
            fi
          done

          echo "::error::No release candidate on $sha has a passing release run."
          echo "::error::Candidates found: ${rcs:-none}. Wait for CI, or cut a new one."
          exit 1

      - name: extract release notes from CHANGELOG
        run: |
          python3 tools/release_notes.py notes "${{ steps.tag.outputs.tag }}" > /tmp/notes.md
          echo "--- release body ---"
          cat /tmp/notes.md

      - name: create or update the release
        env:
          GH_TOKEN: ${{ github.token }}
          TAG: ${{ steps.tag.outputs.tag }}
        run: |
          # Pre-1.0 and any -rc/-beta suffix ship as prereleases, not "Latest".
          prerelease=""
          case "$TAG" in
            *-rc*|*-beta*|*-alpha*) prerelease="--prerelease" ;;
          esac

          if gh release view "$TAG" >/dev/null 2>&1; then
            echo "Release $TAG exists — updating notes."
            gh release edit "$TAG" --notes-file /tmp/notes.md
          else
            # shellcheck disable=SC2086
            gh release create "$TAG" \
              --title "$TAG" \
              --notes-file /tmp/notes.md \
              $prerelease
          fi