release.yml

name: Release

# Publishing is triggered by a version tag and nothing else (FR-019a). The tag is created by
# tag-on-merge.yml, so the approval -> merge -> tag -> publish ordering is enforced by the
# platform rather than by convention (FR-007f).

on:
  push:
    tags: ['v[0-9]+.[0-9]+.[0-9]+']

permissions:
  contents: write # create the GitHub release for the tag
  id-token: write # OIDC for PyPI trusted publishing and provenance (FR-021a, FR-021b)

jobs:
  publish:
    runs-on: ubuntu-latest
    environment: pypi
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
        with:
          python-version: '3.12'

      - name: The tag must match the packaged version
        run: |
          # Every tag in this repository, and in api-reference, carries the v. The version
          # inside the package never does, so the tag is compared with it stripped.
          TAG="${GITHUB_REF_NAME#v}"
          PKG="$(cat VERSION)"
          [ "$TAG" = "$PKG" ] || { echo "tag $TAG != VERSION $PKG"; exit 1; }

      - run: uv build

      # Assert the artifact, not just the file. setuptools derives the version from VERSION, but a
      # broken pyproject.toml still builds: it silently produced flat_api-0.0.0 once. PyPI never
      # lets a version be replaced, so this has to fail here rather than after the upload.
      - name: The built artifact must carry the tagged version
        run: |
          # Every tag in this repository, and in api-reference, carries the v. The version
          # inside the package never does, so the tag is compared with it stripped.
          TAG="${GITHUB_REF_NAME#v}"
          test -f "dist/flat_api-${TAG}-py3-none-any.whl" || {
            echo "no wheel for ${TAG}; dist/ holds:"; ls dist/; exit 1;
          }
          test -f "dist/flat_api-${TAG}.tar.gz" || {
            echo "no sdist for ${TAG}; dist/ holds:"; ls dist/; exit 1;
          }

      # No long-lived token exists: PyPI trusts this repository and workflow by OIDC.
      - name: Skip the publish if this version is already on PyPI
        id: published
        run: |
          VERSION="${GITHUB_REF_NAME#v}"
          if curl -fsS "https://pypi.org/pypi/flat-api/$VERSION/json" >/dev/null 2>&1; then
            echo "flat-api $VERSION is already on PyPI; nothing to publish."
            echo "skip=true" >> "$GITHUB_OUTPUT"
          else
            echo "skip=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Publish to PyPI (trusted publishing)
        if: steps.published.outputs.skip != 'true'
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          attestations: true

      # A bare tag tells a reader nothing. This gives the version a page carrying its changelog
      # section, and it is what a watcher of this repository is notified about.
      - name: Publish the GitHub release
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          # The release is named for the tag. The version inside the package never carries the v,
          # so the changelog lookup and the install line use it stripped.
          VERSION="${GITHUB_REF_NAME#v}"
          NOTES="$(awk -v v="$VERSION" '
            $0 ~ "^## \\[?" v "\\]?" { found = 1; next }
            found && /^## / { exit }
            found { print }
          ' CHANGELOG.md)"
          [ -n "$NOTES" ] || NOTES="See CHANGELOG.md for $VERSION."
          printf '%s\n\n---\n\nInstall: `pip install flat-api==%s`\n' "$NOTES" "$VERSION" > /tmp/notes.md
          # Creating one that exists is an error, and a re-run of a release that already happened
          # should be a no-op rather than a red build.
          if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
            echo "Release $GITHUB_REF_NAME already exists; nothing to do."
          else
            gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file /tmp/notes.md --verify-tag
          fi