fix(ci): make a failed publish retryable, and unpin the stale twine

v0.11.0 was tagged and its GitHub Release created, but the PyPI upload failed:

    Checking dist/hotdata_framework-0.11.0-py3-none-any.whl:
    ERROR InvalidDistribution: Invalid distribution metadata:
          '2.5' is not a valid metadata version

Nothing to do with the code. gh-action-pypi-publish was pinned at v1.13.0
(Sept 2025), whose bundled twine predates `Metadata-Version: 2.5`, which current
hatchling emits. Bumped to v1.14.2.

Note the build job's own `twine check --strict` PASSED, because it
pip-installs a current twine. So the incompatibility was invisible until upload,
by which point the tag was already public -- the check that exists to catch bad
metadata cannot catch this class at all.

RETRYABILITY IS THE REAL FIX. Both workflows triggered only on tag push, so a
publish that failed for reasons unrelated to the code left two bad options:
delete and re-push the tag, or burn a version number on a CI fix. Neither is a
reasonable answer to "the upload failed, run it again". Both now accept a
workflow_dispatch with a tag input, checkout that ref, and derive the version
from it.

release.yml gets the same treatment for a second reason: RELEASING.md already
documents the recovery command

    gh workflow run "GitHub Release" --ref main -f tag=vX.Y.Z

and the trigger it needs was never there, so that documented path has always
failed. This makes the doc true.

Verified both files parse with triggers ['push', 'workflow_dispatch'] and a
`tag` input, and no GITHUB_REF_NAME references remain in either.

Author: anoop-narang

.github/workflows/publish.yml

@@ -4,9 +4,20 @@ on:
   push:
     tags:
       - 'v[0-9]*'
+  # Retry an existing tag without moving it. A publish can fail for reasons that
+  # have nothing to do with the code — a stale action pin, a PyPI outage — and
+  # with only the tag trigger the choices were to delete and re-push the tag or
+  # to burn a version number on a CI fix. Neither is a good answer to
+  # "the upload failed, run it again".
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing tag to build and publish (e.g. v1.2.3)
+        required: true
+        type: string
 
 concurrency:
-  group: pypi-publish-${{ github.ref_name }}
+  group: pypi-publish-${{ inputs.tag || github.ref_name }}
   cancel-in-progress: false
 
 permissions:
@@ -16,8 +27,13 @@ jobs:
   build:
     name: Build distribution
     runs-on: ubuntu-latest
+    env:
+      # The tag being released, whether it arrived by push or by dispatch.
+      TAG: ${{ inputs.tag || github.ref_name }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ inputs.tag || github.ref_name }}
 
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
@@ -28,11 +44,11 @@ jobs:
 
       - name: Verify tag matches pyproject version
         run: |
-          if [[ ! "$GITHUB_REF_NAME" =~ ^v[0-9] ]]; then
-            echo "Release tag '$GITHUB_REF_NAME' must start with 'v' followed by a digit (e.g. v1.0.0)" >&2
+          if [[ ! "$TAG" =~ ^v[0-9] ]]; then
+            echo "Release tag '$TAG' must start with 'v' followed by a digit (e.g. v1.0.0)" >&2
             exit 1
           fi
-          tag="${GITHUB_REF_NAME#v}"
+          tag="${TAG#v}"
           pkg_version=$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
           if [ "$tag" != "$pkg_version" ]; then
             echo "Release tag ($tag) does not match pyproject.toml version ($pkg_version)" >&2
@@ -65,5 +81,10 @@ jobs:
           name: dist
           path: dist/
 
+      # v1.13.0's bundled twine rejects `Metadata-Version: 2.5`, which current
+      # hatchling emits: `InvalidDistribution: '2.5' is not a valid metadata
+      # version`. The build job's own `twine check --strict` passes, because it
+      # pip-installs a current twine — so the failure appears only at upload,
+      # after the tag is already public.
       - name: Publish via Trusted Publishing
-        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

.github/workflows/release.yml

@@ -4,6 +4,16 @@ on:
   push:
     tags:
       - 'v[0-9]*'
+  # RELEASING.md already documents this recovery path — "If PyPI publish
+  # succeeded but the GitHub Release workflow failed, rerun it from main without
+  # retagging" — but the trigger it needs was never here, so the documented
+  # command has always failed. Adding it makes the doc true.
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing tag to create or update a Release for (e.g. v1.2.3)
+        required: true
+        type: string
 
 permissions:
   contents: write
@@ -12,8 +22,13 @@ jobs:
   release:
     name: Create GitHub Release
     runs-on: ubuntu-latest
+    env:
+      # The tag being released, whether it arrived by push or by dispatch.
+      TAG: ${{ inputs.tag || github.ref_name }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ inputs.tag || github.ref_name }}
 
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
@@ -23,15 +38,15 @@ jobs:
         id: meta
         run: |
           pkg_name=$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['name'])")
-          pkg_version="${GITHUB_REF_NAME#v}"
+          pkg_version="${TAG#v}"
           echo "name=${pkg_name}" >> "$GITHUB_OUTPUT"
           echo "version=${pkg_version}" >> "$GITHUB_OUTPUT"
 
       - name: Extract changelog notes
         id: notes
         run: |
           set -euo pipefail
-          version="${GITHUB_REF_NAME#v}"
+          version="${TAG#v}"
           if [[ -f CHANGELOG.md ]]; then
             body="$(python scripts/extract-changelog.py "$version")"
           else
@@ -47,7 +62,7 @@ jobs:
       - name: Create GitHub Release
         uses: softprops/action-gh-release@da05d552573ad5aba039eaac05058a918a7bf631 # v2.2.2
         with:
-          tag_name: ${{ github.ref_name }}
+          tag_name: ${{ inputs.tag || github.ref_name }}
           name: ${{ steps.meta.outputs.name }} ${{ steps.meta.outputs.version }}
           body: ${{ steps.notes.outputs.body }}
           generate_release_notes: false