Releasing to PyPI

kinenix, kinenix-hub, and kinenix-worker are released together with one version number. Users install them with:

pip install kinenix              # core engine and the kinenix CLI
pip install "kinenix[worker]"    # adds kinenix-worker
pip install "kinenix[hub]"       # adds kinenix-hub (the `kinenix hub` command)

kinenix-studio is not published yet.

Publishing runs in GitHub Actions (.github/workflows/release.yml) with PyPI Trusted Publishing: PyPI trusts this repository's workflow directly, so no API token is stored anywhere.

1. One-time setup

1.1 Trusted publishers on PyPI

Sign in to https://pypi.org with the account that owns kinenix.

Use these values:

A pending publisher turns into the project on the first successful upload.

Each package has its own environment, and the release workflow publishes each one in its own job: kinenix first, then kinenix-hub and kinenix-worker.

• A job gets one OIDC token from PyPI, scoped to the publisher that matches the job's environment. When one environment matches the publishers of several projects (for example the active publisher of kinenix and a pending one for kinenix-hub), the token is valid for only one of them and the other uploads fail with 403 Invalid API Token: OIDC scoped token is not valid for project.
• PyPI also refuses two pending publishers with the same owner, repository, workflow, and environment ("A pending trusted publisher matching this configuration has already been registered for a different project name").

Once a project exists, a pending publisher can no longer be added for it; add the publisher in the project's own settings (Manage, then Publishing) instead.

1.2 Trusted publishers on TestPyPI

Repeat 1.1 on https://test.pypi.org (a separate site with its own account), with environment names testpypi for kinenix, testpypi-hub for kinenix-hub, and testpypi-worker for kinenix-worker. Use it to try every release before the real one.

1.3 GitHub environments (recommended)

The workflow creates the pypi, pypi-hub, pypi-worker, testpypi, testpypi-hub, and testpypi-worker environments on first use. To require approval before anything is published, open the repository Settings, then Environments, then pypi, pypi-hub, and pypi-worker, and add yourself under Required reviewers.

2. Making a release

Released version numbers can never be reused on PyPI or TestPyPI. If something is wrong after an upload, fix it and release the next version (for example 0.2.0b2).

1. Bump the version in a pull request into dev. Change all of these to the same value; a test fails if they differ:
2. __version__ in kinenix-core/kinenix/__init__.py, kinenix-hub/kinenix_hub/__init__.py, and kinenix-worker/kinenix_worker/__init__.py
3. kinenix-hub>= and kinenix-worker>= in the extras of kinenix-core/pyproject.toml
4. kinenix>= in the dependencies of kinenix-hub/pyproject.toml and kinenix-worker/pyproject.toml
5. Merge dev into main through the usual release pull request. CI builds the packages, checks their metadata, and installs them in a clean environment.
6. Try it on TestPyPI: in GitHub, open Actions, then Release, then Run workflow on main. When it finishes, check in a new virtual environment:

   pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ "kinenix[hub,worker]==0.2.0b1"
   kinenix --version
   kinenix-worker --version
   

7. Publish to PyPI by tagging main:

   git switch main && git pull
   git tag v0.2.0b1
   git push origin v0.2.0b1
   

   The workflow builds again, checks that the tag matches the package version, and publishes all three packages.
8. Check https://pypi.org/project/kinenix/, kinenix-hub, and kinenix-worker, then install from PyPI in a clean environment.

3. Upgrading an installation

pip install --upgrade "kinenix[hub]"      # or "kinenix[worker]"

On Windows, stop any running kinenix hub or kinenix-worker from that environment first. Windows locks the running kinenix.exe, so pip can remove the old version but fail to install the new one, leaving kinenix uninstalled. If that happens, stop the process and run the same command again. A folder named like ~inenix-...dist-info left in site-packages by the failed attempt can be deleted.

On a Raspberry Pi running the systemd service: sudo systemctl stop kinenix-worker, upgrade, then sudo systemctl start kinenix-worker.

Order of upgrades from 0.2.0b3 or older

1. Upgrade every worker first. Kinenix 0.2.0b3 and older do not know ## On Error and ## Finally: they run those steps as ordinary steps, so an error e-mail would be sent on every successful run. Deploy flows that use them only after every machine that runs them has 0.2.0b4 or newer (kinenix version), and add > Requires: kinenix>=0.2.0b4 under their titles.
2. Upgrade the Hub. The first start migrates hub.db in place and fills in the steps, failures, and run reports of the runs already stored; on a large database that start takes longer. Back up hub.db first (stop the Hub, then copy it).
3. Optionally replace the Hub settings in each worker's environment with kinenix connect http://<hub>:8080.

Each release's changes and upgrade notes are in CHANGELOG.md.

4. What the checks cover