openarena용 Trusted Publishing 릴리스 파이프라인: 지금은 TestPyPI, PyPI는 repo 플래그 뒤에

# GitHub Actions Release Workflow

## `.github/workflows/release.yml`

```yaml
name: Release

on:
  release:
    types: [published]
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: release-${{ github.ref }}
  cancel-in-progress: false

jobs:
  build:
    name: Build distribution
    runs-on: ubuntu-latest
    timeout-minutes: 15
    outputs:
      version: ${{ steps.version.outputs.version }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: astral-sh/setup-uv@v5
        with:
          enable-cache: false

      - name: Set dev version for manual runs
        if: github.event_name == 'workflow_dispatch'
        run: uv version --frozen "$(uv version --frozen --short).dev${{ github.run_number }}"

      - name: Verify tag matches pyproject version
        if: github.event_name == 'release'
        run: |
          tag="${GITHUB_REF_NAME#v}"
          pkg_version="$(uv version --frozen --short)"
          if [ "$tag" != "$pkg_version" ]; then
            echo "::error::Tag '$GITHUB_REF_NAME' (=$tag) does not match pyproject version '$pkg_version'"
            exit 1
          fi

      - name: Read version
        id: version
        run: echo "version=$(uv version --frozen --short)" >> "$GITHUB_OUTPUT"

      - name: Build
        run: uv build

      - name: Check metadata
        run: uvx twine check dist/*

      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/
          if-no-files-found: error

  publish-testpypi:
    name: Publish to TestPyPI
    needs: build
    runs-on: ubuntu-latest
    timeout-minutes: 10
    if: >-
      github.event_name == 'workflow_dispatch' ||
      github.event.release.prerelease ||
      vars.PUBLISH_PYPI != 'true'
    environment:
      name: testpypi
      url: https://test.pypi.org/p/${{ github.event.repository.name }}
    permissions:
      id-token: write
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/

      - uses: pypa/gh-action-pypi-publish@release/v1
        with:
          repository-url: https://test.pypi.org/legacy/

  publish-pypi:
    name: Publish to PyPI
    needs: build
    runs-on: ubuntu-latest
    timeout-minutes: 10
    if: >-
      github.event_name == 'release' &&
      !github.event.release.prerelease &&
      vars.PUBLISH_PYPI == 'true'
    environment:
      name: pypi
      url: https://pypi.org/p/${{ github.event.repository.name }}
    permissions:
      id-token: write
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/

      - uses: pypa/gh-action-pypi-publish@release/v1

  verify:
    name: Verify install
    needs: [build, publish-testpypi, publish-pypi]
    if: >-
      always() &&
      (needs.publish-testpypi.result == 'success' || needs.publish-pypi.result == 'success')
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install and smoke-test
        env:
          PKG: ${{ github.event.repository.name }}
          VERSION: ${{ needs.build.outputs.version }}
          FROM_TESTPYPI: ${{ needs.publish-testpypi.result == 'success' }}
        run: |
          set -euo pipefail
          pkg="${PKG//-/_}"
          if [ "$FROM_TESTPYPI" = "true" ]; then
            install_cmd="pip download --no-deps --only-binary :all: -i https://test.pypi.org/simple/ ${PKG}==${VERSION} && pip install ${PKG}==${VERSION} --no-deps --no-cache-dir"
          else
            install_cmd="pip install ${PKG}==${VERSION} --no-cache-dir"
          fi

          ok=0
          for i in $(seq 1 30); do
            if [ "$FROM_TESTPYPI" = "true" ]; then
              if pip download --no-deps --only-binary :all: --no-cache-dir \
                   -i https://test.pypi.org/simple/ \
                   -d /tmp/wheels "${PKG}==${VERSION}" >/dev/null 2>&1; then
                if pip install --no-cache-dir --no-deps /tmp/wheels/*.whl >/dev/null 2>&1 \
                   && pip install --no-cache-dir "${PKG}==${VERSION}" >/dev/null 2>&1; then
                  ok=1; break
                fi
              fi
            else
              if pip install --no-cache-dir "${PKG}==${VERSION}" >/dev/null 2>&1; then
                ok=1; break
              fi
            fi
            echo "Attempt $i/30 failed; retrying in 10s..."
            sleep 10
          done
          if [ "$ok" -ne 1 ]; then
            echo "::error::Package ${PKG}==${VERSION} not installable after 5 minutes"
            exit 1
          fi

          "${PKG}" --help >/dev/null
          python -c "import ${pkg}"
          python -c "import importlib.metadata as m; assert m.version('${PKG}') == '${VERSION}', m.version('${PKG}')"

          mkdir -p /tmp/smoke && cd /tmp/smoke
          "${PKG}" init
          "${PKG}" check

          {
            echo "### Verified \`${PKG}==${VERSION}\`"
            echo ""
            echo '```'
            echo "$install_cmd"
            echo '```'
          } >> "$GITHUB_STEP_SUMMARY"
```

## `README.md` — absolute links

Replace relative image and license references so they render on PyPI:

```markdown
![logo](https://raw.githubusercontent.com/OWNER/REPO/main/docs/assets/logo.png)

[LICENSE](https://github.com/OWNER/REPO/blob/main/LICENSE)
```

## `docs/releasing.md`

```markdown
# Releasing

## Trial builds

Run the **Release** workflow manually (`workflow_dispatch`). The build job sets the
version to `<pyproject>.dev<run_number>` using `uv version --frozen` (pyproject only;
`uv.lock` is not re-resolved), builds, and publishes to TestPyPI. The verify job
installs the wheel from TestPyPI with dependencies from PyPI and runs `init` + `check`.

## Releases

1. Bump the version in `pyproject.toml` and commit.
2. Tag `v<version>` and publish a GitHub release.
3. The build job fails if the tag (minus `v`) differs from the pyproject version.
4. Non-pre-releases publish to PyPI only when the repository variable
   `PUBLISH_PYPI` is `true`; otherwise they go to TestPyPI.

## Pre-releases

Mark the GitHub release as a pre-release. It always publishes to TestPyPI and never
to PyPI, regardless of `PUBLISH_PYPI`.

## No re-upload rule

PyPI and TestPyPI reject re-uploading an existing version. Never reuse a version
number — bump it and cut a new release. Manual runs use `.dev<run_number>` so they
never collide.
```

## Dependency pin

If a dependency's new minor version breaks imports, pin it in `pyproject.toml`:

```toml
dependencies = [
    "some-dep>=1.2,<1.3",
]
```

## Local validation

```bash
uv build
uvx twine check dist/*
uv run ruff check .
uv run pytest
uv run mkdocs build --strict
actionlint -shellcheck=shellcheck .github/workflows/release.yml
```