Route pre-releases to TestPyPI and full releases to PyPI

The single upload job published everything to PyPI, so there was no way to
rehearse an upload without consuming the real version number -- and neither
index lets a version be reused, even after deletion.

Now the GitHub release decides. A release tagged v* publishes to TestPyPI if it
is marked a pre-release and to PyPI if it is not; the two conditions are
mutually exclusive, so nothing lands on both. Tagging v1.10.0rc1 as a
pre-release therefore exercises the whole path -- OIDC, metadata, wheel tags,
upload -- and leaves 1.10.0 untouched. It is also a legitimate pre-release
rather than a wasted number, since 1.10.0rc1 sorts before 1.10.0.

The v-prefix check is unchanged and still applies to both: binaries-* releases
carry prebuilt archives, not a Python package, and must never reach an index.

Verified that v1.10.0rc1 resolves to 1.10.0rc1 under the configured tag_regex.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: fedorov

.github/workflows/cd.yml

@@ -117,21 +117,53 @@ jobs:
       - name: Show wheel tags
         run: ls -la all/*/*
 
-  upload_all:
+  # Where a release goes is decided by two things, both read off the GitHub release itself.
+  #
+  # The tag prefix picks out releases *of this package*. build-binaries.yml also publishes
+  # GitHub releases -- tagged binaries-<version>-<n>, carrying the prebuilt plastimatch
+  # archives that plastimatchUrls.cmake pins -- and those must never reach an index. Without
+  # the tag check every one of them would trigger an upload of a wheel built from whatever the
+  # pins happened to reference at the time.
+  #
+  # The prerelease flag then picks the index. Mark the release a pre-release (and tag it
+  # v<version>rc<n>) to rehearse on TestPyPI; a full release publishes to PyPI. Nothing goes to
+  # both, so a rehearsal cannot consume the real version number -- which matters because
+  # neither index ever lets a version be reused, even after deletion.
+
+  upload_testpypi:
+    name: Publish to TestPyPI
+    needs: [check_dist]
+    environment: testpypi
+    permissions:
+      id-token: write
+    runs-on: ubuntu-latest
+    if: >-
+      github.event_name == 'release' && github.event.action == 'published'
+      && startsWith(github.event.release.tag_name, 'v')
+      && github.event.release.prerelease
+
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: cibw-*
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  upload_pypi:
     name: Publish to PyPI
     needs: [check_dist]
     environment: pypi
     permissions:
       id-token: write
     runs-on: ubuntu-latest
-    # Only v-prefixed tags are releases of this package. build-binaries.yml also publishes
-    # GitHub releases -- tagged binaries-<version>-<n>, carrying the prebuilt plastimatch
-    # archives that plastimatchUrls.cmake pins -- and those must never reach PyPI. Without the
-    # tag check every one of them would trigger an upload, publishing a wheel built from
-    # whatever the pins happened to reference at the time.
     if: >-
       github.event_name == 'release' && github.event.action == 'published'
       && startsWith(github.event.release.tag_name, 'v')
+      && !github.event.release.prerelease
 
     steps:
       - uses: actions/download-artifact@v8

README.md

@@ -228,27 +228,40 @@ not reachable that way, so repointing the pins at a private repository breaks ev
 build, not just CI. This is why the pins still reference the fork: that repository is public.
 
 **2. Register a Trusted Publisher**, so there is no API token to manage. Because the project
-does not exist on PyPI yet, this is a *pending* publisher, added at
-<https://pypi.org/manage/account/publishing/>:
+does not exist on either index yet, these are *pending* publishers:
 
-| Field | Value |
-| --- | --- |
-| PyPI project name | `plastimatch` |
-| Owner | the account or organisation owning this repository at publish time |
-| Repository name | `plastimatch-python-distributions` |
-| Workflow name | `cd.yml` |
-| Environment name | `pypi` |
+| Field | PyPI | TestPyPI |
+| --- | --- | --- |
+| Register at | <https://pypi.org/manage/account/publishing/> | <https://test.pypi.org/manage/account/publishing/> |
+| Project name | `plastimatch` | `plastimatch` |
+| Owner | `ImagingDataCommons` | `ImagingDataCommons` |
+| Repository name | `plastimatch-python-distributions` | `plastimatch-python-distributions` |
+| Workflow name | `cd.yml` | `cd.yml` |
+| Environment name | `pypi` | `testpypi` |
 
 The owner must match wherever the repository actually lives when the workflow runs — an OIDC
-claim is checked against it, so registering the wrong owner fails the upload. Register it after
-any planned move, not before.
+claim is checked against it, so registering the wrong owner fails the upload. Register after
+any planned move, not before. The environment names must match the `environment:` keys on the
+`upload_pypi` and `upload_testpypi` jobs in `cd.yml`.
+
+Both environments are created automatically on first use, but creating them explicitly with a
+required reviewer makes every publish need a human approval — recommended for `pypi`, given
+that uploads cannot be undone.
 
-Registering the same on <https://test.pypi.org/manage/account/publishing/> allows a rehearsal,
-which is worth doing because a published version can never be reused.
+### Cutting a release
+
+Which index a release goes to is decided by the GitHub release itself, so nothing ever lands on
+both and a rehearsal cannot consume the real version number:
+
+| Release | Tag | Publishes to |
+| --- | --- | --- |
+| pre-release | `v1.10.0rc1` | TestPyPI |
+| full release | `v1.10.0` | PyPI |
 
-The `pypi` GitHub environment referenced by `cd.yml` is created automatically on first use, but
-creating it explicitly with a required reviewer makes every publish need a human approval —
-recommended, given that uploads cannot be undone.
+So the sequence is: tag `v1.10.0rc1` and mark the GitHub release as a pre-release, confirm the
+upload and that `pip install -i https://test.pypi.org/simple/ plastimatch` gives a working
+executable, then tag `v1.10.0` as a full release. `1.10.0rc1` sorts before `1.10.0`, so the
+rehearsal is also a legitimate pre-release rather than a number burned for nothing.
 
 Two things worth knowing before the first upload: