diff --git a/README.md b/README.md index be9db54..7d64062 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/docs/get_started.en.md b/docs/get_started.en.md new file mode 100644 index 0000000..63b4504 --- /dev/null +++ b/docs/get_started.en.md @@ -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//`; 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. diff --git a/docs/publishing.en.md b/docs/publishing.en.md new file mode 100644 index 0000000..6a5ea4b --- /dev/null +++ b/docs/publishing.en.md @@ -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//`; 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//`. + +```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 ` or `ORISYS_VERIFY_VIDEO`; the gate should report +failure rather than silently claiming a pass. + +For one existing wheel, `release audit ` 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 +python build/run.py release pypi --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.