================ Supplier’s Guide ================ Scope ===== This guide is for a **supplier** producing an auditable evidence shipment for a component/SEooC (documentation + traceability + implementation + tests + analysis/verification reports + integrity metadata). The goal is to provide a package that allows an integrator to: - understand intended use and limitations - reuse evidence where appropriate - complete context-specific safety analysis and verification Supplier deliverables ===================== Documentation deliverables -------------------------- Provide a structured documentation set: - safety goals and safety requirements (``REQ_SAFETY_*``) - functional requirements (``REQ_FUNC_*``) - architecture/design constraints (``ARCH_*``) - verification requirements and methods (``TEST_*``) - traceability matrices demonstrating coverage For a full CLI command/option reference, see :doc:`cli_reference`. Operational assumptions (critical) ---------------------------------- Document assumptions clearly: - environment ranges (temperature, vibration, EMC/noise) - sampling rates, timing budgets, scheduling assumptions - sensor characteristics and calibration assumptions - expected failure modes and diagnostic coverage boundaries Interface specification ----------------------- Provide stable interface definitions: - signal names, units, ranges, validity rules - error reporting behavior - initialization and degraded mode behavior - timing constraints and performance limits Verification artifacts ---------------------- Provide machine-readable test output when possible (e.g., JUnit XML), and record tool versions/configuration. Traceability export and shipment integrity ------------------------------------------ In OSQAr, an example build output directory can be treated as a **software shipment**: it is the unit that is transferred to the integrator and stored as evidence. For each shipped example output, include the following files **inside the shipped directory**: - ``needs.json``: machine-readable export of all requirements/architecture/tests (from ``sphinx-needs``) - ``traceability_report.json``: machine-readable check result (generated by OSQAr tooling) - ``SHA256SUMS``: checksum manifest for the entire shipped directory (generated by OSQAr tooling) - ``osqar_project.json``: optional project metadata/config (description, URLs, origin; and optionally project-side build/test commands and hooks) .. note:: Integrators should treat configuration inside received bundles as untrusted input. Use supplier-provided ``osqar_project.json`` for descriptive metadata (origin/URLs), but only execute commands/hooks from trusted integrator-side configuration. Recommended supplier procedure (per example) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Run the example end-to-end workflow (tests → reports → docs). This produces a shippable bundle directory (by default: ``examples/python_hello_world/_build/html``) that contains documentation with traceability, plus implementation/tests and analysis reports. On macOS/Linux (native shell script):: cd examples/python_hello_world ./build-and-test.sh On Windows, prefer the cross-platform CLI flow (or run the shell script under WSL2):: osqar shipment prepare \ --project examples/python_hello_world \ --clean 2. Run traceability checks and write a JSON report:: osqar traceability examples/python_hello_world/_build/html/needs.json \ --json-report examples/python_hello_world/_build/html/traceability_report.json 3. Generate a checksum manifest for the example build output directory and verify it immediately:: osqar checksum generate \ --root examples/python_hello_world/_build/html \ --output examples/python_hello_world/_build/html/SHA256SUMS osqar checksum verify \ --root examples/python_hello_world/_build/html \ --manifest examples/python_hello_world/_build/html/SHA256SUMS Optional convenience: the same steps are available via higher-level OSQAr CLI workflows:: # One-shot shipment workflow (recommended) osqar shipment prepare \ --project examples/python_hello_world \ --clean \ --archive # Or run the individual shipment steps osqar build-docs --project examples/python_hello_world osqar shipment traceability --shipment examples/python_hello_world/_build/html osqar shipment checksums --shipment examples/python_hello_world/_build/html generate osqar shipment checksums --shipment examples/python_hello_world/_build/html verify 4. Ship the example build output directory as a ZIP archive, keeping ``SHA256SUMS`` at the root of the shipped directory. Optional: add project metadata into the shipment directory (recommended for multi-project integrators):: osqar shipment metadata write \ --shipment examples/python_hello_world/_build/html \ --name "OSQAr Python Hello World" \ --version "0.4.2" \ --url repository=https://example.com/repo.git \ --origin url=https://example.com/repo.git \ --origin revision= Optional: declare dependencies on other OSQAr-qualified libraries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If your shipped component depends on other OSQAr-qualified components, declare them in the shipped ``osqar_project.json`` under ``dependencies``. Each dependency entry includes a pin: - ``pin_sha256sums`` is a SHA-256 over the dependency shipment's ``SHA256SUMS`` file bytes. Compute a pin from a built/received dependency shipment directory:: osqar shipment pin --shipment /path/to/LIB_PROVIDER_shipment Then add the dependency entry to your metadata (example): .. code-block:: json { "schema": "osqar.shipment_project_metadata.v1", "id": "LIB_CONSUMER", "version": "1.2.3", "dependencies": [ { "id": "LIB_PROVIDER", "version": "2.0.0", "pin_sha256sums": "" } ] } Integrator workspaces can then enforce dependency closure across all received shipments using ``--enforce-deps``. Notes ^^^^^ - Generate checksums **per example build output**, not site-wide. The OSQAr framework docs (repo root build) are not part of the example shipment. - Keep requirement IDs stable across releases; the exported artifacts are designed to be diffed and archived. - For higher assurance, sign ``SHA256SUMS`` externally (e.g., detached signature) and store it separately from the shipment. Change control and versioning ============================= Version the supplier package and include: - a changelog describing safety-impacting changes - compatibility notes (interfaces, configuration) - migration guidance for integrators How to use OSQAr as a supplier ============================== - Start from the reference chapter structure and keep it consistent. - Treat requirement IDs as a contract; keep them stable across releases. - Provide review-friendly traceability with both ``:links:`` and explicit tables. - Ship an evidence bundle (rendered HTML, sources, diagrams, test outputs, toolchain metadata). Integrator handoff ================== Clarify: - intended use and out-of-scope behavior - assumptions that must be validated during integration - safety-relevant configuration parameters - what evidence is reusable vs must be redone in context