新增 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,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.