orisys-sdk/docs/publishing.en.md

---
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;
`wheel-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 wheel-manylinux
python build/run.py wheel-manylinux -Architecture aarch64
```

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.

Build Windows x64, Linux x86_64 and Linux ARM64 before preparing the release
report. With Python 3.10, 3.11 and 3.12 this produces nine wheels. Both publishers
use every wheel in `SDK/<version>/`; files added or rebuilt after preflight
invalidate its certification. ARM64 CPU wheels do not require CUDA.

## 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
```

`--all-wheel-pythons` checks every staged ABI and architecture. Run the complete
mixed-platform gate from Windows: Windows wheels use the `py310`, `py311` and
`py312` conda environments, while Linux wheels use `orisys-manylinux` or
`orisys-manylinux-aarch64` with the matching container Python. Docker must already
have these locally built images; verification never pulls or rebuilds them.
Linux dependencies come from each image's ABI wheelhouse, in an isolated venv.
ARM64 verification on Intel/AMD uses QEMU and can take longer. Every wheel must
pass imports, bundled-asset loading and the CPU video pipeline; emulation does
not certify Q6A or Jetson hardware, GPU or NPU behavior.

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.
The report must also contain successful runtime evidence matching every wheel's
hash. Older reports that checked only Windows wheels must be regenerated.

```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.

The release order is build all candidates, commit source changes, run the clean
preflight, preview both publishers, then execute the authorized publications.
GitHub attaches all certified wheels and generates notes naming their actual
platforms, including ARM64. PyPI defaults to TestPyPI first; after confirming it,
use `--confirm-pypi --apply` for production. Each upload checks the complete
filename set and downloads every Python/platform wheel from that index to
compare its hash. TestPyPI download verification does not fall back to PyPI.
If downloads are not yet available, the command reports the successful upload
as unconfirmed and stops before uploading to later indexes; check propagation
before rerunning.
If a published version has a different file set, the commands stop rather than
silently extending or replacing that release.