Skip to content

RELEASING.md

Latest commit

 

History

History
119 lines (88 loc) · 4.22 KB

RELEASING.md

File metadata and controls

119 lines (88 loc) · 4.22 KB

Releasing blockchain0x (Python SDK)

Sub-plan 21.3 row G-1. 3-step procedure for publishing a new version of the Python SDK to PyPI as blockchain0x.

Prerequisites (one-time, owner)

  1. PyPI account + project: register the blockchain0x project on https://pypi.org/. The owner who runs the publish workflow must be a maintainer or owner of that project.

  2. Public mirror repo: create the public repo Tosh-Labs/blockchain0x-python (Apache-2.0; default branch main; no README/license at creation - the first mirror snapshot supplies them).

  3. GitHub PAT: mint a fine-grained PAT with Contents: read+write on Tosh-Labs/blockchain0x-python only. Store as the secret MIRROR_TO_PUBLIC_GITHUB_PAT_TOKEN on Tosh-Labs/blockchain0x-app (reused across SDK mirror workflows).

  4. PyPI Trusted Publisher binding: on the project's PyPI settings page (Publishing tab), add a new publisher with:

    • Publisher: GitHub
    • Owner: Tosh-Labs
    • Repository name: blockchain0x-python
    • Workflow filename: publish.yml
    • Environment: pypi (matches the environment: pypi field in the publish workflow)

    Trusted Publisher OIDC replaces any long-lived API token; no PYPI_TOKEN secret is needed.

Release flow

Step 1 - bump the version on dev

The Python SDK does not yet have a npm version-equivalent helper, so edit packages/sdk-python/pyproject.toml directly:

[project]
version = "0.0.2a0"  # was "0.0.1a0"

PEP 440 pre-release tags: 0.0.2a0 is alpha 0; 0.0.2b0 is beta 0; 0.0.2rc1 is release-candidate 1; 0.0.2 is the final release.

Commit + push to dev:

git add packages/sdk-python/pyproject.toml
git commit -m "chore(sdk-python): bump to 0.0.2a0"
git push origin dev

Step 2 - mirror to the public repo

From the GitHub Actions tab on Tosh-Labs/blockchain0x-app:

  1. Open the mirror-sdk-python workflow.
  2. Click Run workflow -> branch dev. The default dry_run=false is correct for a real release; toggle dry_run=true first if you want to preview the staged snapshot.
  3. The workflow:
    • reads the version from pyproject.toml,
    • runs a stdlib-only Python smoke test (compiles every file + verifies webhooks.verify round-trips),
    • stages the snapshot into /tmp/snapshot/,
    • replaces the public repo's contents with the snapshot,
    • commits, tags vX.Y.Z, and pushes.

Step 3 - publish from the public repo

On Tosh-Labs/blockchain0x-python:

  1. Open the publish workflow.
  2. Click Run workflow -> branch main. The tag input is informational (PyPI infers alpha/beta from the version string per PEP 440); pick alpha for the typical pre-release iteration.
  3. The workflow:
    • builds sdist + wheel via python -m build,
    • validates metadata via twine check,
    • publishes to PyPI via the pypa/gh-action-pypi-publish action, which exchanges the GitHub OIDC token for a short-lived PyPI publish token through the Trusted Publisher binding.

pip install blockchain0x==0.0.2a0 is live within ~1 minute.

Verify the release

pip install --upgrade blockchain0x
python -c "import blockchain0x; print(blockchain0x.__version__)"
python -c "from blockchain0x import webhooks; print(webhooks.SIGNATURE_MISSING)"

webhooks.SIGNATURE_MISSING should print webhook.signature_missing.

Rollback

PyPI does NOT permit overwriting a published version. A bad release is yanked (still in the index but excluded from pip install resolution) and a fixed version published:

# On pypi.org, navigate to the version row and click "Options" -> "Yank"
# with a short reason ("regression: <description>").

Then bump pyproject.toml to the NEXT patch and re-run Steps 1-3.

Cross-references