---
title: Build and publish the Orisys SDK
description: Contributor release checklist and the verified build and publish entry points.
---

# Build and publish the Orisys SDK

This guide gives contributors the path from a source change to release evidence.
The build launcher is [build/run.py](../build/run.py), documented in
[build/README.md](../build/README.md). Publishing to GitHub or PyPI changes external
systems and is a maintainer action. The existing
[Chinese release runbook](publishing.md) retains historical details; verify its
version-specific examples against current code before using them.

## Before building

Run the non-hardware tests from the repository root with the intended Python
environment:

```bash
python -m pytest -m "not slow and not hardware"
```

Check the current SDK version at `src/orisys/__init__.py`. `pyproject.toml` reads it
as a dynamic version. Do not copy a previous release number into new commands or
documentation. Check the source diff and confirm the intended product bundles and
assets are present; `pyproject.toml` declares which non-code files are packaged.

## Build the candidate

Use the launcher appropriate to the target. `wheel-win` invokes the Windows build;
`manylinux` invokes the Docker-backed Linux build. A single-interpreter `wheel`
build is useful for a local candidate, but does not cover every supported ABI.

```bash
python build/run.py wheel-win
python build/run.py manylinux
```

Windows builds use the configured `py310`, `py311`, and `py312` environments.
The Linux build needs its documented Docker setup. Built wheels are placed under
`SDK/<version>/`; Linux upload candidates may also appear in `dist/repaired/`.
See [build/README.md](../build/README.md) for build prerequisites and narrower
commands. A contributor without these environments can still run tests and hand
off a source change; do not describe it as a verified release candidate.

## Run the release gate

After building, run `release preflight` on a clean, reviewed commit. It checks
repository state, version consistency, tests, bundled assets, wheel contents, and
an isolated runtime on recorded frames. `--check-pypi` adds a read-only duplicate
version check against PyPI. The report is written under
`build/release/reports/<version>/`.

```bash
python build/run.py release preflight --all-wheel-pythons --check-pypi
```

For work in progress, `--allow-dirty --keep-going` can collect diagnostics, but
that report does **not** certify a release. Do not use `--skip-tests`, `--no-runtime`,
or `--no-assets` to turn missing verification into approval. If the runtime clip is
missing, provide `--video <path>` or `ORISYS_VERIFY_VIDEO`; the gate should report
failure rather than silently claiming a pass.

For one existing wheel, `release audit <wheel>` checks it without preparing a
complete release. Add `--assets --runtime` when a suitable verification clip and
environment are available. This is useful for investigating a candidate; it does
not replace the full preflight gate.

## Release handoff and publication

Hand the maintainer the version, source commit, wheel filenames, preflight report,
and any hardware or platform checks that were not run. The publish commands read
the passing preflight report and verify the wheel hashes again.

```bash
python build/run.py release github --version <version>
python build/run.py release pypi --version <version>
```

These commands omit `--apply`, so they preview the publish plan. The GitHub preview
may still fetch remote tags; the PyPI preview may check credentials and the index.
Maintainers run the commands with `--apply` only after checking the target repository,
release notes, credentials, and candidate files. `release pypi --apply` targets
TestPyPI; publishing to the production index also requires `--confirm-pypi`.
GitHub publication can sync the release mirror, commit, tag, push, and create a
Release. See the launcher help and [build/README.md](../build/README.md) for the
exact flags. A published version cannot be overwritten, so do not treat a rerun as
a way to replace bad wheels.