orisys-sdk/docs/publishing.en.md

title, description

title	description
Build and publish the Orisys SDK	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, documented in build/README.md. Publishing to GitHub or PyPI changes external systems and is a maintainer action. The existing Chinese release runbook 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:

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.

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

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.

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