Setting Up A Project From Scratch

This guide shows how to adopt OSQAr for a new component project or how to migrate an existing component into OSQAr.

The focus is practical:

  • how to scaffold a project using the built-in OSQAr CLI

  • where to copy your existing sources and tests

  • how to migrate existing documentation into OSQAr’s traceable chapters

  • how to ship the next release of a fictitious open-source library with an OSQAr evidence shipment

Prerequisites

  • Python + Poetry installed

  • OSQAr available (either cloned from this repository, or vendored into your component repository)

  • Your component has (or will have) automated tests that can emit JUnit XML

Install options

  • Core docs + CLI (lean default):

    poetry install

  • Optional evidence tooling used by the example scripts (coverage + complexity):

    poetry install --with evidence

Mental model

An OSQAr project is a Sphinx documentation project. The output of building that project (typically _build/html) becomes the evidence shipment directory that you archive and transfer.

A shipment is intended to be reviewable end-to-end and typically contains:

  • rendered HTML documentation with traceability

  • exported trace graph (needs.json)

  • integrity manifest (SHA256SUMS)

  • implementation sources and tests (for review/audit)

  • raw verification outputs (e.g. test_results.xml) and analysis reports

Step 1 — Choose a template and scaffold

OSQAr ships a CLI that can copy a language template into a new project folder.

Install OSQAr via pipx (recommended): pipx install osqar

# Example: create a new C-based component project
osqar new \
  --language c \
  --name OpenThermoLib \
  --destination ../OpenThermoLib

cd ../OpenThermoLib

What you get

The scaffolded project is a standalone Sphinx project with a familiar OSQAr chapter layout (requirements → architecture → verification → implementation → test results → lifecycle management).

Typical layout (simplified):

OpenThermoLib/
  conf.py
  index.rst
  01_requirements.rst
  02_architecture.rst
  03_verification.rst
  04_implementation.rst
  05_test_results.rst
  06_lifecycle_management.rst
  src/
  include/
  tests/
  build-and-test.sh

Note

Some templates and examples use build-and-test.sh for end-to-end automation. On Windows, prefer the Python CLI workflows (documented in Using the OSQAr Boilerplate) or run the shell scripts under WSL2.

Step 2 — Copy your existing sources and tests

If you are migrating an existing component, the simplest approach is:

  • keep the component’s original repository as-is, but add OSQAr documentation at the repo root

  • or create a new OSQAr-based repository and copy your code into it

Where to put code

Follow the template conventions (they match the OSQAr example projects):

  • C: src/ + include/ + tests/

  • C++: src/ + include/ + tests/

  • Rust: src/ (Cargo crate) + tests/ (or Rust integration tests) + Cargo.toml

  • Python: src/ + tests/

If your repository already uses different paths, you can keep them and simply adjust:

  • the build script (e.g. build-and-test.sh)

  • the documentation chapter that references implementation locations

Tests and JUnit XML

OSQAr’s example documentation can import JUnit XML. Make sure your test run produces a stable file, commonly:

  • test_results.xml at the project root

If you already produce JUnit XML elsewhere (e.g. build/test_results.xml), either:

  • copy it to test_results.xml as part of your build script, or

  • adjust the Sphinx config / test report import paths in your project.

Step 3 — Migrate component documentation into OSQAr chapters

Most existing open-source component documentation can be migrated by splitting it into OSQAr’s traceable chapters.

A practical mapping:

  • README.md and design notes → 02_architecture.rst

  • API reference snippets → 04_implementation.rst

  • test plan / how-to-test → 03_verification.rst

  • release notes / maintenance policy → 06_lifecycle_management.rst

Make requirements explicit

OSQAr is most valuable when you turn implicit expectations into explicit, traceable needs.

Example requirement (fictitious):

.. need:: (FR) Convert raw sensor counts to temperature.
   :id: REQ_FUNC_CONVERT_001
   :status: active
   :links: ARCH_API_001, TEST_CONVERT_001

   The library shall convert ADC counts to degrees Celsius using a configurable calibration model.

Keep IDs stable and meaningful: once you ship a requirement ID in a release, treat it as a long-lived identifier.

Architecture and diagrams

If your project already has diagrams:

  • export them to PlantUML where feasible

  • store PlantUML sources under diagrams/ and include them from RST

Example:

.. uml:: diagrams/01_context.puml
   :caption: Context and boundaries

Verification chapter

Use 03_verification.rst to define verification requirements (TEST_*) and link them back to requirements/architecture.

Example:

.. need:: (TEST) Conversion covers full ADC range.
   :id: TEST_CONVERT_001
   :status: active
   :links: REQ_FUNC_CONVERT_001

   Verification method: unit test.

Step 4 — Build an evidence shipment locally

A minimal “supplier build” flow is:

  1. run tests (produce test_results.xml)

  2. generate optional analysis reports (coverage/complexity)

  3. build docs (exports needs.json)

  4. generate traceability report + checksums

If your project uses the provided script:

poetry install --with evidence
./build-and-test.sh

If you prefer the CLI one-shot flow:

osqar shipment prepare \
  --project . \
  --clean \
  --archive

The shipped directory is typically _build/html.

Worked example: shipping the next release of a fictitious library

Scenario

Assume you maintain a fictitious open-source library:

  • Name: OpenThermoLib

  • Purpose: domain-agnostic temperature conversion + thresholding helper library

  • Language: C

  • Next release: v1.4.0

Goal: ship v1.4.0 together with an OSQAr evidence shipment.

Release checklist (supplier)

1) Freeze scope and update metadata

  • update your CHANGELOG.md

  • ensure requirement IDs are stable (do not rename IDs lightly)

  • ensure tests are deterministic (no timestamps in JUnit XML if you can avoid it)

2) Produce a reproducible build

# Use the release commit timestamp for stable build metadata
export SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)"

# Build and collect evidence
poetry install --with evidence
OSQAR_REPRODUCIBLE=1 ./build-and-test.sh

3) Generate integrity metadata and a traceability report

osqar traceability _build/html/needs.json \
   --json-report _build/html/traceability_report.json

osqar checksum generate \
   --root _build/html \
   --output _build/html/SHA256SUMS

osqar checksum verify \
   --root _build/html \
   --manifest _build/html/SHA256SUMS

4) Archive the shipment for distribution

# Example naming convention
osqar shipment package \
   --shipment _build/html \
   --output OpenThermoLib_v1.4.0_evidence_shipment.zip

# Optional: verify checksums again after moving/copying the directory

5) Publish the release

Common open-source pattern:

  • create a git tag v1.4.0

  • create a GitHub Release

  • attach:

    • the source archive (GitHub auto-generates)

    • OpenThermoLib_v1.4.0_evidence_shipment.zip

For higher assurance, consider signing the shipped checksum manifest externally (e.g., detached signature) and storing signatures separately.

Integrator-side intake (quick view)

An integrator who receives the shipment typically:

  • verifies SHA256SUMS

  • optionally re-runs traceability checks on shipped needs.json

  • archives the shipment immutably

Example:

osqar checksum verify \
    --root /path/to/OpenThermoLib_shipment \
    --manifest /path/to/OpenThermoLib_shipment/SHA256SUMS

osqar traceability \
    /path/to/OpenThermoLib_shipment/needs.json \
    --json-report /path/to/OpenThermoLib_shipment/traceability_report.integrator.json

Next steps