=========================== Using the OSQAr Boilerplate =========================== This chapter is the main entrypoint for OSQAr. It explains the **mental model** (project → shipment → workspace) and provides **copy/paste workflows**. For the full per-command reference (all flags, exit codes, and resolution rules), see :doc:`cli_reference`. What OSQAr Is For ================= OSQAr is a **documentation-first framework** for producing, verifying, and integrating **auditable evidence shipments** for safety/compliance work. An evidence shipment is the unit you transfer and archive: a bundle that contains: - rendered Sphinx documentation (with traceability) - implementation sources and tests - verification artifacts (test reports, analysis summaries, traceability reports) - integrity protection (checksum manifest) OSQAr’s core ingredients: - structured requirements and traceability (via ``sphinx-needs``) - architecture diagrams (via PlantUML) - verification planning (requirements ↔ architecture ↔ tests) - shipment and workspace workflows (prepare, verify, intake, report) How To Use This Guide ===================== 1. Run :ref:`quick-start` to build docs and generate a scaffold. 2. Read :ref:`terms` once (project vs shipment vs workspace). 3. Use :ref:`workflow-recipes` as your day-to-day command cookbook. 4. When you need exact flags/help, jump to :doc:`cli_reference`. .. _quick-start: Quick Start (End-to-End) ======================== .. note:: The examples below use the PyPI-installed CLI. - Install OSQAr once: ``pipx install osqar`` - Invoke commands as: ``osqar ...`` If you are contributing to OSQAr from a git clone and did not install via pipx, use the repo-root wrappers instead (``./osqar`` on Linux/macOS; ``osqar.cmd`` / ``osqar.ps1`` on Windows). .. code-block:: console # 0) Install the OSQAr CLI pipx install osqar # 1) Install dependencies (this repo / framework docs) poetry install # 2) Build the framework docs (repo root) osqar build-docs # 3) Scaffold a minimal project next to the framework repo osqar new --language c --name MySEooC --destination ../MySEooC # 4) Build the scaffolded project docs osqar build-docs --project ../MySEooC Windows note: prefer the Windows repo-root wrappers (``osqar.cmd`` / ``osqar.ps1``). If you want to run the example ``*.sh`` scripts unchanged, use WSL2. Recommended reading order ========================= 1. You are here: build docs, understand the workflow, and explore examples. 2. Set up and migrate a project: :doc:`project_setup_from_scratch`. 3. As a supplier, learn how to ship evidence bundles: :doc:`suppliers_guide`. 4. As an integrator, learn how to verify and archive shipments: :doc:`integrators_guide`. 5. If you work with many shipments, use: :doc:`multi_project_workflows`. 6. For release/baseline discipline, see: :doc:`lifecycle_management`. 7. For team-scale collaboration, see: :doc:`collaboration_workflows`. Workflow overview ================= 1. Author needs objects (REQ/ARCH/TEST) in RST with stable IDs. 2. Build HTML docs and export machine-readable artifacts (e.g. ``needs.json``). 3. Run traceability checks and keep the report. 4. Generate a checksum manifest (e.g. ``SHA256SUMS``). 5. Transfer/archive the shipment; integrators verify checksums and (optionally) re-run checks. Installation options (Poetry groups) ==================================== OSQAr keeps the default Python dependency footprint lean. Install additional tooling only if you need it: - Core docs + CLI (recommended default):: poetry install - Evidence tooling (coverage/complexity generation used by example scripts):: poetry install --with evidence - IDE tooling (optional Sphinx language server for VS Code):: poetry install --with ide Download (optional) =================== If you want pre-built archives (example workspaces / demo shipments) without building locally, use the GitHub Releases assets: - https://github.com/bitvortex/OSQAr/releases If you downloaded the combined example workspace ZIP from Releases (often together with a ``.sha256`` file), extract and verify it with: .. code-block:: console osqar setup osqar_example_workspace_.zip .. _terms: Terminology (Project, Shipment, Workspace) ========================================== These terms are used consistently across the docs and the CLI. They match the definitions in :doc:`cli_reference`. Project (shipment project) -------------------------- Directory that contains at least: - ``conf.py`` - ``index.rst`` Examples live under ``examples/``. Shipment directory (built evidence output) ------------------------------------------ The built HTML output directory, usually: - ``/_build/html`` This directory may contain artifacts such as ``index.html``, ``needs.json``, ``SHA256SUMS``, and reports. Workspace (integrator side) --------------------------- A directory that contains **multiple received shipments**. Workspace commands typically discover shipments by scanning for ``SHA256SUMS`` in subdirectories. Declared dependencies (pins) ---------------------------- OSQAr supports **workspace dependency closure** for OSQAr-qualified libraries. If a shipped component depends on other OSQAr-qualified components, the supplier can declare those dependencies in the shipped ``osqar_project.json``. Each dependency is identified by: - ``id`` - ``version`` - ``pin_sha256sums`` (a SHA-256 over the dependency shipment's ``SHA256SUMS`` file bytes) Suppliers can compute the pin from a built/received shipment directory: .. code-block:: console osqar shipment pin --shipment /path/to/LIB_PROVIDER_shipment Integrators can enforce that all declared dependencies are present (and unambiguous) in a workspace: .. code-block:: console osqar workspace verify --root intake/received --recursive --enforce-deps See :doc:`multi_project_workflows` for the full dependency resolution rules and how to observe logical deduplication. .. _workflow-recipes: Workflow Recipes ================ The commands below are the “core loop” you’ll run most often. Build docs (Sphinx HTML) ------------------------ .. code-block:: console # Build docs for the current project (default: --project .) osqar build-docs # Build docs for an example project osqar build-docs --project examples/c_hello_world # Build and open index.html osqar build-docs --open Verify traceability ------------------- OSQAr’s traceability check validates basic rules based on exported ``needs.json``. .. code-block:: console osqar traceability ./_build/html/needs.json \ --json-report ./_build/html/traceability_report.json Checksum manifest (shipment integrity) -------------------------------------- Generate and verify a checksum manifest (default: SHA-256) for a shipped directory. .. code-block:: console osqar checksum generate \ --root ./_build/html \ --output ./_build/html/SHA256SUMS \ --json-report ./_build/html/checksums_report.generate.json osqar checksum verify \ --root ./_build/html \ --manifest ./_build/html/SHA256SUMS \ --json-report ./_build/html/checksums_report.verify.json Prepare and verify a shipment (high-level) ------------------------------------------ If you want one command that builds docs, runs checks, and optionally archives: .. code-block:: console # Supplier side: build a shippable evidence directory osqar shipment prepare --project examples/python_hello_world --clean --archive # Integrator side: verify a received shipment osqar shipment verify --shipment /path/to/shipment --traceability \ --report-json /path/to/shipment/verify_report.json Reproducible native builds (C / C++ / Rust) =========================================== OSQAr’s documentation builds are already dependency-locked via Poetry. For **native code** (C/C++/Rust), OSQAr also provides a small “reproducible build” mode in the examples. The goals are: - stable timestamps (via ``SOURCE_DATE_EPOCH``) - stable embedded source paths (via compiler path remapping) - reduced build-environment noise (UTC timezone + stable locale) The example build scripts accept either the environment flag ``OSQAR_REPRODUCIBLE=1`` or the CLI flag ``--reproducible``. .. code-block:: bash # Use the latest git commit timestamp as a stable build time export SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)" # C example cd examples/c_hello_world OSQAR_REPRODUCIBLE=1 ./build-and-test.sh # C++ example cd ../cpp_hello_world OSQAR_REPRODUCIBLE=1 ./build-and-test.sh # Rust example cd ../rust_hello_world OSQAR_REPRODUCIBLE=1 ./build-and-test.sh Notes: - The reproducible mode is implemented as a small helper script (vendored into each example at ``osqar_tools/reproducible_build_env.sh``) and is intentionally lightweight. - The shipped *test report XML* in the examples does not include timestamps, so it is stable across runs. Optional: Bazel integration --------------------------- If you prefer Bazel for a more “CI-native” workflow, the C, C++, and Rust examples include minimal Bazel files. Reproducible mode for Bazel is supported via the wrapper script in each example (it applies the same path remapping and stable environment as the non-Bazel scripts, and runs Bazel with ``--config=reproducible``). .. code-block:: bash cd examples/c_hello_world # Non-reproducible (default) bazel build //... bazel run //:junit_tests -- test_results.xml # Reproducible export SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)" OSQAR_REPRODUCIBLE=1 ./bazel-build-and-test.sh cd ../cpp_hello_world bazel build //... bazel run //:junit_tests -- test_results.xml export SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)" OSQAR_REPRODUCIBLE=1 ./bazel-build-and-test.sh cd ../rust_hello_world bazel build //... bazel run //:junit_tests -- test_results.xml export SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)" OSQAR_REPRODUCIBLE=1 ./bazel-build-and-test.sh CI-built demo shipments (downloadable) ====================================== This repository’s CI builds **downloadable, integrity-protected example shipments** for the C, C++, and Rust examples. Each example shipment contains: - rendered HTML documentation (with maintained traceability) - implementation sources and tests - analysis/verification reports: - ``test_results.xml`` (JUnit) - ``coverage_report.txt`` (coverage summary; language-specific tooling) - ``complexity_report.txt`` (complexity summary) - ``needs.json`` (trace graph export) - ``traceability_report.json`` (OSQAr traceability validation output) - ``SHA256SUMS`` (checksum manifest for the whole bundle directory) CI exports deterministic archives (``.tar.gz``) for each example as well as a combined archive. CI exports deterministic-ish ZIP archives for each example shipment **and** a combined example workspace. In GitHub Actions, download the artifact named ``osqar-example-workspace`` from the ``Tests and Example Shipments`` workflow run. For the repository’s CI configuration (including reproducible build settings), see :ref:`ci-setup`. Reference examples ================== OSQAr primarily targets **C**, **C++**, and **Rust** projects. Each example produces: - native test results as ``test_results.xml`` (JUnit) - rendered HTML documentation; the examples can optionally import JUnit XML into the docs via ``sphinx-test-reports`` Build any example documentation directly: .. code-block:: bash poetry install osqar build-docs --project examples/c_hello_world osqar build-docs --project examples/cpp_hello_world osqar build-docs --project examples/rust_hello_world Run an end-to-end workflow (native tests → docs) for an example: .. code-block:: bash # Optional: install extra tooling to generate coverage/complexity evidence poetry install --with evidence cd examples/c_hello_world ./build-and-test.sh open _build/html/index.html Python demo (workstation reference) ----------------------------------- A Python example remains available as a documentation reference variant: .. code-block:: bash # Optional: install extra tooling to generate coverage/complexity evidence poetry install --with evidence cd examples/python_hello_world ./build-and-test.sh open _build/html/index.html OSQAr CLI ========= OSQAr includes a small, stdlib-only CLI for common workflows: - scaffold a new project from a language template - validate traceability based on an exported ``needs.json`` - generate/verify checksum manifests for a shipped evidence bundle - supplier and integrator workflows (prepare, verify, intake) - optional shipment metadata (origin, URLs, descriptive info) For guidance on large-team collaboration (branching, merging, conflict minimization), see :doc:`collaboration_workflows`. Full command reference (all subcommands and flags): :doc:`cli_reference`. Shell scripts and Windows support --------------------------------- OSQAr includes a number of shell scripts (primarily ``*.sh``) across the repository. They exist for two reasons: - **Example automation and CI parity**: the example projects (C/C++/Rust/Python) ship end-to-end scripts (tests → evidence files → docs) so users can reproduce what the CI and GitHub Pages workflows do. - **Developer convenience**: a small number of scripts help with local workflows. Design decision (pragmatic cross-platform support) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This repository intentionally does **not** try to provide a Windows-native equivalent for every ``.sh`` script. Reasons: - Many scripts assume a POSIX shell and common Unix tooling (Bash, coreutils, path conventions, executable bits). - Reproducible-build packaging is much harder to keep consistent across platforms (e.g., stable ZIP creation, stable file ordering, stable timestamps). Instead, OSQAr uses: - A **cross-platform primary entry point**: the installed CLI (``osqar``). - Repo-root wrappers for contributors and offline use (``./osqar`` on Linux/macOS; ``osqar.cmd`` / ``osqar.ps1`` on Windows). - A documented fallback for running example scripts on Windows: **WSL2** (recommended) or a POSIX-like environment such as Git Bash. What this means in practice ^^^^^^^^^^^^^^^^^^^^^^^^^^^ - If you are on Windows and want the supplier/integrator workflows, prefer the CLI. It covers the common steps (build docs, run traceability checks, generate/verify checksums, archive shipments). - If you specifically want to run the example ``build-and-test.sh`` scripts unchanged, run them in WSL2. Support matrix ^^^^^^^^^^^^^^ .. list-table:: Support matrix (recommended expectations) :header-rows: 1 :widths: 34 22 22 22 * - Workflow - Linux/macOS - Windows (native) - Windows (WSL2) * - Run OSQAr CLI workflows (scaffold, traceability, checksums, supplier/integrator) - Supported - Supported (recommended) - Supported * - Run example ``build-and-test.sh`` scripts unchanged - Supported - Not supported (use CLI, or run under WSL2) - Supported (recommended) * - Reproducible builds and deterministic shipment archives - Supported (CI reference) - Best-effort (tooling differences) - Supported (closest to CI) Windows-friendly equivalents (recommended) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following are intended as portable alternatives to the example scripts: .. code-block:: bash # Build docs and prepare an evidence shipment via the CLI osqar shipment prepare \ --project examples/python_hello_world \ --clean \ --archive For more context on the CI workflows and how these scripts are used in automation, see :ref:`ci-setup`. Scaffold a new project ---------------------- Create a new project folder based on one of the reference templates: For a step-by-step guide (including how to migrate existing sources and documentation, and how to ship a release with OSQAr evidence), see :doc:`project_setup_from_scratch`. .. code-block:: bash osqar new --language c --name MySEooC --destination ./MySEooC This copies the selected template while excluding build outputs (e.g., ``_build/``, ``target/``, ``__pycache__/``). Verify traceability ------------------- Run traceability checks on an exported ``needs.json``: .. code-block:: bash osqar traceability ./_build/html/needs.json \ --json-report ./_build/html/traceability_report.json Checksum manifest (shipment integrity) -------------------------------------- Generate and verify a checksum manifest (default: SHA-256) for a shipped directory: .. code-block:: bash osqar checksum generate \ --root ./_build/html \ --output ./_build/html/SHA256SUMS \ --json-report ./_build/html/checksums_report.generate.json osqar checksum verify \ --root ./_build/html \ --manifest ./_build/html/SHA256SUMS \ --json-report ./_build/html/checksums_report.verify.json Core authoring workflow ======================= OSQAr works best when you keep a consistent structure: - define requirements and constraints as ``.. need::`` objects with stable IDs - link requirements ↔ architecture ↔ tests using ``:links:`` and ``:need:`ID``` references - keep architecture diagrams in PlantUML sources under version control - define verification requirements (``TEST_*``) and include traceability tables/matrices (e.g. via ``sphinx-needs`` directives) Writing requirements (sphinx-needs) ----------------------------------- A requirement is defined using a ``.. need::`` directive with a stable ``:id:``. .. code-block:: rst .. need:: (SR) Detect overheat within 100ms. :id: REQ_SAFETY_002 :status: active :tags: timing :links: REQ_SAFETY_001, ARCH_FUNC_003, TEST_END_TO_END_001 **Architecture**: :need:`ARCH_FUNC_003` **Tests**: :need:`TEST_END_TO_END_001` Recommended ID scheme --------------------- The boilerplate enforces ID discipline via ``needs_id_regex``. A practical scheme is: - ``REQ_SAFETY_*``: safety goals and safety requirements - ``REQ_FUNC_*``: functional requirements - ``ARCH_*``: architecture/design constraints and interfaces - ``TEST_*``: verification requirements / test specifications Architecture diagrams (PlantUML) -------------------------------- PlantUML sources live in ``diagrams/`` and are included from RST: .. code-block:: rst .. uml:: diagrams/02_data_flow.puml :caption: Data flow (budget: :need:`REQ_SAFETY_002`) — Architecture: :need:`ARCH_FUNC_001`, :need:`ARCH_FUNC_002`, :need:`ARCH_FUNC_003` Verification and traceability ----------------------------- A robust verification chapter typically contains: 1) test requirements as needs objects (``TEST_*``) 2) a traceability matrix mapping ``REQ_*``/``ARCH_*`` → ``TEST_*`` Traceability into source code (“best of both worlds”) ---------------------------------------------------------------- In practice, teams often want two complementary views of traceability: 1) **Documentation-level traceability** (auditor-friendly): ``REQ_*`` ↔ ``ARCH_*`` ↔ ``TEST_*`` links in Sphinx via ``sphinx-needs``. 2) **Code-level traceability** (engineer-friendly): the same IDs appear in implementation and test code comments near the relevant functions. OSQAr supports using both together: - In the docs, create a code-level need (commonly ``CODE_*`` or ``IMPL_*``) as an *evidence anchor*. Link it to the corresponding ``REQ_*``/``ARCH_*``/``TEST_*`` needs, and embed/attach the actual sources: - Use ``literalinclude`` to embed excerpts directly into the shipped HTML. - Use ``:download:`` to attach full files for review. - In the code, tag the relevant locations with IDs so reviewers can find the implementation quickly. Examples (language-agnostic): - Implementation: mention ``REQ_*`` and ``ARCH_*`` near the function/module that implements it. - Tests: mention ``TEST_*`` near the test that realizes the verification requirement. Optional CI check: validate IDs in code ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To keep the code tags from drifting, you can scan sources and optionally enforce simple coverage rules. Generate a report (non-failing by default): .. code-block:: bash osqar code-trace \ --root . \ --needs-json ./_build/html/needs.json \ --json-report ./_build/html/code_trace_report.json Enforce that every documented ID is mentioned in code (useful in CI): .. code-block:: bash osqar code-trace \ --root . \ --needs-json ./_build/html/needs.json \ --enforce-req-in-impl \ --enforce-arch-in-impl \ --enforce-test-in-tests Shipment verification (per example output) ========================================== OSQAr treats each **example build output directory** as a shippable evidence bundle. This is the unit that is transferred, archived, and later verified (similar to a software shipment). Per shipped example output directory, OSQAr expects the following files to be present: - ``needs.json`` (export from ``sphinx-needs``) - ``traceability_report.json`` (result of the OSQAr traceability check) - ``SHA256SUMS`` (checksum manifest covering the full directory contents) - ``osqar_project.json`` (optional project metadata: description, URLs, origin) Supplier-side procedure (create the shipment) --------------------------------------------- Build the example documentation so that ``needs.json`` is exported:: osqar build-docs --project examples/python_hello_world Run the traceability check (writes a machine-readable report):: osqar traceability examples/python_hello_world/_build/html/needs.json \ --json-report examples/python_hello_world/_build/html/traceability_report.json Generate and verify checksums for the example build output directory:: osqar checksum generate \ --root examples/python_hello_world/_build/html \ --output examples/python_hello_world/_build/html/SHA256SUMS \ --json-report examples/python_hello_world/_build/html/checksums_report.generate.json osqar checksum verify \ --root examples/python_hello_world/_build/html \ --manifest examples/python_hello_world/_build/html/SHA256SUMS \ --json-report examples/python_hello_world/_build/html/checksums_report.verify.json Optional convenience (higher-level workflows in one command):: # Build a shippable evidence directory in one command osqar shipment prepare \ --project examples/python_hello_world \ --clean \ --archive # Verify a received shipment (checksums + traceability) osqar shipment verify \ --shipment /path/to/shipment \ --traceability \ --report-json /path/to/shipment/verify_report.json # Supplier: optionally add metadata into the shipment root osqar shipment metadata write \ --shipment examples/python_hello_world/_build/html \ --name "OSQAr Python Hello World" \ --version "1.0.0" \ --url repository=https://example.com/repo.git \ --origin url=https://example.com/repo.git \ --origin revision= # Integrator: intake multiple shipments and generate a Subproject overview osqar workspace intake \ --root intake/received \ --recursive \ --output intake/archive/2026-02-01 \ --traceability # Optional: enforce declared OSQAr-qualified dependencies osqar workspace verify \ --root intake/received \ --recursive \ --enforce-deps # Optional: compute a stable dependency pin for a shipment (SHA256SUMS) osqar shipment pin --shipment /path/to/shipment # Generate and open an HTML Subproject overview (via Sphinx) osqar workspace report \ --root intake/received \ --recursive \ --output intake/overview \ --open # Show explicit checksums/traceability status in the HTML overview osqar workspace report \ --root intake/received \ --recursive \ --output intake/overview \ --checksums \ --traceability \ --open # 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 Then archive and ship the **example output directory** (not the framework docs built from the repo root). For multi-project intake patterns, see :doc:`multi_project_workflows`. Integrator-side procedure (verify a received shipment) ------------------------------------------------------ Verify the received directory against the provided manifest:: osqar checksum verify \ --root /path/to/shipment \ --manifest /path/to/shipment/SHA256SUMS Optionally re-run the traceability checks on the shipped ``needs.json``:: osqar traceability /path/to/shipment/needs.json \ --json-report /path/to/shipment/traceability_report.integrator.json For role-specific guidance (including what to do on mismatches), see: - :doc:`suppliers_guide` - :doc:`integrators_guide` We also recommend getting familiar with suggestions on overall lifecycle management: - :doc:`lifecycle_management` Code complexity (optional) ========================== OSQAr supports generating additional *engineering evidence* artifacts alongside test results. All reference examples include an optional **code complexity report** step that produces ``complexity_report.txt``. - **C / C++ / Python**: `lizard `_ (Cyclomatic Complexity) - Runs as part of the example scripts via ``poetry run lizard``. - You can run it manually from the repository root, e.g.: .. code-block:: bash poetry install --with evidence poetry run lizard -C 10 examples/c_hello_world/src examples/c_hello_world/include - **Rust**: `cargo-cyclo `_ (Cyclomatic Complexity) - Install once: ``cargo install cargo-cyclo`` - Then run from within the Rust example: .. code-block:: bash cd examples/rust_hello_world cargo cyclo The example scripts treat complexity reporting as **best-effort** by default (they do not fail the workflow if the tool is not installed). For CI, you can tighten this to enforce thresholds. Troubleshooting =============== - PlantUML in offline environments: set ``PLANTUML_JAR`` or install PlantUML locally. - Broken trace links: prefer ``:need:`ID``` references over plain-text IDs. - ID validation failures: keep IDs uppercase with underscores (e.g., ``REQ_SAFETY_001``).