新增 SDK 贡献者英文入门与发布指南

让源码开发和发布交接有清晰入口，并保留现有中文文档。文档门禁与标定测试通过。
2026-10-05 13:29:36 +08:00
parent 34cb83d4a4
commit 8c147f03aa
3 changed files with 170 additions and 2 deletions
@@ -0,0 +1,89 @@
+---
+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.