Skip to content

docs(release): cover TestPyPI verification and fix stale wheel-download notes#1760

Merged
andygrove merged 2 commits into
apache:mainfrom
andygrove:docs-release-pypi-verify
May 24, 2026
Merged

docs(release): cover TestPyPI verification and fix stale wheel-download notes#1760
andygrove merged 2 commits into
apache:mainfrom
andygrove:docs-release-pypi-verify

Conversation

@andygrove
Copy link
Copy Markdown
Member

Which issue does this PR close?

Closes #.

Rationale for this change

Worked through the Python wheel release docs end-to-end on the 53.0.0-rc1-pypitest-3 tag and hit a few rough edges and stale pieces:

  • The verification docs ("Verifying Release Candidates") only cover the Rust tarball script. They do not mention that RC verifiers can also install the wheels from TestPyPI to sanity-check the Python artifacts before voting.
  • dev/release/download-python-wheels.py aborts in non-interactive shells because the gpg signing step needs a TTY for pinentry. There is no warning in the docs and the failure mode is confusing.
  • The expected-files list pins the manylinux_2_17 glibc tag, but the runner image now produces manylinux_2_39 wheels (and that number will keep moving as the GitHub-hosted runner advances).
  • The fallback advice says "the build-sdist job currently does not upload its output as a workflow artifact." That is no longer true after ci: produce real aarch64 wheel and upload sdist artifact #1753, which added a dist-sdist artifact. The local-rebuild command in that same block uses maturin build --release --sdist --out dist, which was the broken command (it produces both a wheel and an sdist) fixed in ci: use maturin sdist subcommand to avoid building a wheel #1759.
  • The per-platform fallback download still references dist-windows-latest, but ci: pin Windows wheel builder to windows-2022 #1751 renamed it to dist-windows-2022. It also omits the new dist-sdist.
  • The TestPyPI smoke test runs python -m venv against whatever python is on PATH. On macOS that is 3.9, and pip then reports a misleading "No matching distribution found" because the wheels are cp310-abi3 (Python ≥ 3.10).

What changes are included in this PR?

dev/release/README.md only:

  • New "(Optional) Verify the Python wheels from TestPyPI" subsection under "Verifying Release Candidates".
  • Note next to download-python-wheels.py explaining the gpg/non-TTY failure mode and that the traceback is harmless for a TestPyPI-only dry-run.
  • Wheel-filename list uses manylinux_* globs instead of the hard-coded manylinux_2_17 tag, with a one-line explanation of why.
  • Fallback per-platform gh run download adds dist-sdist and renames dist-windows-latestdist-windows-2022.
  • Drop the stale "build-sdist does not upload" paragraph; replace with a shorter note that local rebuild is rarely needed, using the correct maturin sdist --out dist command.
  • Smoke-test venv uses python3.10 and a comment explains why python alone is not enough.

No code, script, or workflow changes.

Are there any user-facing changes?

Documentation only. No runtime or API impact.

…ad notes

- Add a 'Verify the Python wheels from TestPyPI' subsection under Verifying
  Release Candidates so RC verifiers can install from test.pypi.org if the
  release manager has done the pre-vote dry-run.
- Document that download-python-wheels.py needs an interactive terminal for
  gpg signing; the wheels download fine before the signing step, so a
  TestPyPI-only dry-run can ignore the traceback.
- Replace the manylinux_2_17 wheel filenames in the expected-files list with
  glibc-version-agnostic globs; the runner images advance their glibc tag.
- Drop the 'build-sdist does not upload its output' warning (made stale by
  apache#1753) and fix the local-rebuild fallback to use 'maturin sdist' instead
  of the broken 'maturin build --release --sdist' (fixed in apache#1759, which
  produced both a wheel and an sdist).
- Refresh the per-platform fallback artifact names: dist-windows-2022 (apache#1751)
  and the new dist-sdist artifact.
- Note that the smoke-test venv needs Python >= 3.10; macOS's stock python3
  (3.9) yields a misleading 'No matching distribution' error against the
  cp310-abi3 wheels.
@andygrove andygrove merged commit 1c4b5f8 into apache:main May 24, 2026
5 checks passed
@andygrove andygrove deleted the docs-release-pypi-verify branch May 24, 2026 01:21
Comment thread dev/release/README.md
--extra-index-url https://pypi.org/simple/ \
ballista==${BALLISTA_VERSION}
python -c "from ballista import BallistaSessionContext; print('ok')"
deactivate
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it expected/guaranteed that the new version will be at test.pypi.org ?
If the release manager always uploads the wheel to test.pypi.org then this snippet could be added to dev/release/verify-release-candidate.sh and done automatically.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants