Skip to content

RELEASING.md

Latest commit

 

History

History
71 lines (57 loc) · 2.96 KB

RELEASING.md

File metadata and controls

71 lines (57 loc) · 2.96 KB
Raw

hottub PyPI release

The first Python release is a functional Audio Soak beta. It lets an Owner or Host check production voice readiness, create a members-only Audio Soak, and optionally take it live. The public package is dependency-free and contains only API orchestration code. It does not package the Harmonic browser, audio streams, or Harmonic Engine implementation.

One-time ownership setup

  1. Use a company-controlled PyPI account, require 2FA, and add at least two Hottub owners after the project exists.

  2. The joinhottub/hottub-python GitHub repository has an environment named pypi with a required Hottub reviewer. Do not put a PyPI API token in GitHub.

  3. In PyPI, create a pending Trusted Publisher with exactly:

    • PyPI project name: hottub
    • GitHub owner: joinhottub
    • GitHub repository: hottub-python
    • Workflow filename: publish-hottub-python.yml
    • Environment name: pypi

A pending publisher does not reserve the project name. The first successful upload creates the project and claims it.

Public-content boundary

This repository and every PyPI distribution are public. They may contain only the Python client, its tests, packaging metadata, release automation, and public documentation. Never copy Hottub monorepo history, credentials, private configuration, Harmonic DSP source, algorithms, coefficients, models, benchmarks, debug state, symbols, or binary artifacts here.

First release

The repository owner initiates the release:

  1. Create the pending Trusted Publisher described above immediately before the release. It does not reserve the name.

  2. Review pyproject.toml, especially version and proprietary license metadata.

  3. In GitHub Actions, manually run Publish hottub to PyPI. Enter the exact version (for the first release, 0.1.0) and check the public-publish confirmation. Dispatch only from main; the workflow rejects any other ref.

  4. Watch the version guard, Python 3.10-3.14 tests, distribution checks, and wheel smoke test. Review and approve the protected pypi environment only after those jobs pass.

  5. Confirm https://pypi.org/project/hottub/, add a second company-controlled PyPI Owner, and verify from a clean environment:

    python -m venv .venv
.venv/bin/python -m pip install hottub
.venv/bin/hottub --help

The workflow has no push or tag trigger. This keeps package construction and publication owner-initiated. Trusted Publishing creates short-lived credentials for the upload and publishes package attestations; no long-lived PyPI token is stored in GitHub.

Subsequent releases

Increase the version in both pyproject.toml and src/hottub/_version.py, update package behavior and tests, review the diff, and manually run the same workflow with that version. The workflow fails before testing if the two versions or the confirmed version differ. PyPI releases are immutable; a broken version must be replaced with a new version rather than overwritten.