新增 SDK 贡献者英文入门与发布指南
让源码开发和发布交接有清晰入口，并保留现有中文文档。文档门禁与标定测试通过。
This commit is contained in:
ykcheungab
@@ -114,9 +114,11 @@ that explicit file against the selected device.
|
||||
## Examples and Tools
|
||||
|
||||
- Example entry points: `examples/README.md`
|
||||
- User documentation: `docs/get_started.md`
|
||||
- Contributor start: [docs/get_started.en.md](docs/get_started.en.md)
|
||||
- Chinese installation guide: [docs/get_started.md](docs/get_started.md)
|
||||
- Build launcher: `python build/run.py` (see `build/README.md`)
|
||||
- Manylinux / PyPI binary wheel: `docs/publishing.md`
|
||||
- Build and publish guide: [docs/publishing.en.md](docs/publishing.en.md)
|
||||
- Chinese release runbook: [docs/publishing.md](docs/publishing.md)
|
||||
- Specialized utilities: `tools/`
|
||||
|
||||
## Publishing (Linux manylinux)
|
||||
|
||||
@@ -0,0 +1,77 @@
|
||||
---
|
||||
title: Get started with Orisys SDK development
|
||||
description: Set up a source checkout, run a first test, and find the right example.
|
||||
---
|
||||
|
||||
# Get started with Orisys SDK development
|
||||
|
||||
This guide is for contributors working from the SDK source checkout. Obtain the
|
||||
repository URL from your team, clone it, and change into the `orisys-sdk` directory.
|
||||
If you only need to use a published wheel, follow the
|
||||
[Chinese installation guide](get_started.md). Run the commands below from the
|
||||
repository root.
|
||||
|
||||
## First working loop
|
||||
|
||||
Use Python 3.10, 3.11, or 3.12. The existing README uses conda; an isolated
|
||||
environment keeps another installed `orisys` package from shadowing this checkout.
|
||||
|
||||
```bash
|
||||
conda create -n orisys-dev python=3.10
|
||||
conda activate orisys-dev
|
||||
python -m pip install -e . pytest
|
||||
python -c "import orisys; print(orisys.__version__)"
|
||||
python -m pytest -m "not slow and not hardware" tests/test_calibration.py
|
||||
```
|
||||
|
||||
The editable install makes changes under `src/orisys/` visible without rebuilding a
|
||||
wheel. `pytest.ini` adds `src/` to the test import path. Before debugging a strange
|
||||
import failure, check that `python` and `python -m pip` point to the same environment.
|
||||
The full non-hardware suite is:
|
||||
|
||||
```bash
|
||||
python -m pytest -m "not slow and not hardware"
|
||||
```
|
||||
|
||||
Some tests need a recorded clip. `tests/conftest.py` looks for a repository sample or
|
||||
the path in `ORISYS_TEST_VIDEO`; a missing clip can skip those tests. Inspect the test
|
||||
summary rather than treating a run with unexpected skips as coverage.
|
||||
|
||||
## Run a pipeline
|
||||
|
||||
The examples accept a camera index or, where documented, a video path. Start with
|
||||
the example matching your sensor. A camera example needs the device and its bundle;
|
||||
the test command above does not need physical hardware.
|
||||
|
||||
```bash
|
||||
python examples/basic_pipeline.py -v 0 -c box
|
||||
python examples/basic_pipeline.py -v 0 -c mini
|
||||
python examples/finger_pipeline.py --camera_id 0 --config finger
|
||||
```
|
||||
|
||||
For a video-only first run, see the exact arguments in
|
||||
[examples/README.md](../examples/README.md). GUI examples need the optional GUI
|
||||
dependencies (`python -m pip install -e ".[gui]"`). GPU support is optional; the
|
||||
declared extras are `cuda12` and `cuda13` in [pyproject.toml](../pyproject.toml).
|
||||
Start on CPU unless your task requires a GPU backend.
|
||||
|
||||
## Find the owner of a change
|
||||
|
||||
| What you are changing | Start here |
|
||||
| --- | --- |
|
||||
| SDK API or algorithms | `src/orisys/`, then a focused test in `tests/` |
|
||||
| Product configuration and shipped assets | `sensors/<product>/`; see [sensor bundles](sensor-bundles.md) |
|
||||
| Example behavior | `examples/` and [examples/README.md](../examples/README.md) |
|
||||
| Build or release tooling | `build/` and [build/README.md](../build/README.md) |
|
||||
| Studio UI | The separate `orisys-app` repository |
|
||||
|
||||
`config/` holds legacy configurations. New product-bundle work belongs under
|
||||
`sensors/`. For a physical device's calibration, use a user-selected calibration
|
||||
directory and `device_id`; the [SDK README](../README.md#configuration) describes
|
||||
the path and validation contract. Do not commit individual sensor calibration data
|
||||
to the generic product bundle by accident.
|
||||
|
||||
After a change, run the focused tests first, then the relevant non-hardware suite.
|
||||
If a change requires a camera, record the product, configuration, input, and observed
|
||||
result in your handoff. See [publishing](publishing.en.md) when preparing a release;
|
||||
ordinary development does not require a wheel build or a PyPI account.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user