WIP: Integration process documentation

docs/integration_process/checklist.rst

@@ -0,0 +1,48 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2026 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+Checklist
+=========
+
+Use this as a final review before opening your pull request:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
+
+   * - Step
+     - Done when…
+   * - 1 · Add module (register, regenerate, patches)
+     - module entry added under ``modules.target_sw`` with ``repo`` + ``hash``;
+       ``update_module_from_known_good.py`` ran and generated files committed;
+       patches referenced if needed; ``known_good_correct`` and ``bzlmod-lock``
+       checks green.
+   * - 2 · Documentation
+     - ``needs_json`` added to ``//:docs`` data and toctree entry in
+       ``sw_components.rst``; ``//:docs_combo`` shows the module.
+   * - 3 · Unit tests (default platform)
+     - module compiles and unit tests pass on ``--config=linux-x86_64`` via
+       ``quality_runners.py``; ``metadata`` tuned if needed.
+   * - 4 · Platforms (build & test)
+     - ``score_pkg_bundle`` + ``*.score.json`` added and registered in
+       ``showcases/BUILD`` (ships into every image); ``bazel test
+       @score_my_module//...`` passes.
+   * - 5 · Component tests
+     - *not available yet — to be introduced.*
+   * - 6 · Integration tests
+     - tests added under ``feature_integration_tests/itf``.
+   * - 7 · Reporting
+     - Rust coverage generated; verification/status tables updated.
+   * - 8 · Code quality
+     - formatting, Bazel Clippy (Rust) and the CodeQL/MISRA C++ scan pass.

docs/integration_process/integration_process.rst

@@ -12,5 +12,77 @@
    # SPDX-License-Identifier: Apache-2.0
    # *******************************************************************************
 
+###################
 Integration Process
 ###################
+
+This document is a step-by-step *how-to* for module owners who want to integrate
+their own S-CORE module into the **Reference Integration** — whether for the
+first time, when bringing it back after an exclusion, or to make it part of the
+S-CORE releases in general.
+
+It walks you through everything from registering the module in
+``known_good.json`` over wiring it into the Bazel build, the showcases, the
+images and the CLI, up to adding it to the CI/CD pipelines and the consolidated
+reporting (documentation, coverage and verification reports).
+
+
+What "integration" means here
+=============================
+
+The Reference Integration is a single `Bazel (bzlmod) <https://bazel.build/external/overview#bzlmod>`_
+build that pulls every S-CORE module together at a defined commit, builds them
+against each other and runs their tests, showcases and reports.
+
+Integrating a module is **incremental**: each step below builds on the previous
+one and *extends the reach* of your module a little further into the
+integration. You climb the ladder only as far as your module needs — a pure
+library may stop after it builds in-tree, while a module with a runnable example
+goes all the way to running on every target platform and being exercised by
+integration tests.
+
+The chapters that follow walk this ladder in order. Stop at whatever rung makes
+sense for your module.
+
+
+Prerequisites
+=============
+
+Before you start, make sure that:
+
+* Your module lives in its own GitHub repository under the ``eclipse-score``
+  organization and is a **bzlmod module**, i.e. it has a top-level
+  ``MODULE.bazel`` with a ``module(name = "score_<your_module>")`` declaration.
+* The module name follows the ``score_<name>`` convention (e.g.
+  ``score_communication``). The same name is used as the Bazel
+  ``bazel_dep`` / repository name (``@score_<name>//...``).
+* Your module is registered in the
+  `S-CORE Bazel registry <https://github.com/eclipse-score/bazel_registry>`_ so
+  that it can be resolved as a ``bazel_dep`` during the integration.
+* The module builds and tests pass standalone on all four currently supported
+  target platforms: Linux ``x86_64``, QNX 8 ``x86_64``, Red Hat AutoSD
+  ``x86_64`` and EB corbos Linux (Safety Apps) ``aarch64``.
+* You know the commit hash you want to pin (the integration always pins an exact
+  commit, never a floating branch).
+
+
+The integration steps
+======================
+
+Work through the chapters in order — each one extends the reach of your module a
+little further into the integration:
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   step_1_add_module
+   step_2_documentation
+   step_3_unit_tests
+   step_4_platforms
+   step_5_component_tests
+   step_6_integration_tests
+   step_7_reporting
+   step_8_code_quality
+   checklist
+   reference

docs/integration_process/reference.rst

@@ -0,0 +1,148 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2026 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+Reference
+=========
+
+This section is a catalogue of *what already exists* in the integration — the
+CI checks that run on every change and the consolidated reports — together with
+the touch-point a new module has in each. Use it to understand where your module
+shows up once it is wired in via the steps above. The supported target platforms
+and their images are listed in :ref:`supported_platforms` (Step 4).
+
+.. _ci_checks:
+
+CI checks
+---------
+
+The pipelines live under `.github/workflows <https://github.com/eclipse-score/reference_integration/tree/main/.github/workflows>`_. Most
+operate on ``//...`` and pick up your module without changes; the table says
+what each check verifies and whether you typically need to touch anything.
+
+**Gating** marks the checks that run in the merge queue
+(``merge_group``) and must therefore be green before a pull request can be
+merged. The remaining checks are informational, run only on ``push``/schedule,
+or gate a different event (release approvals). The definitive list of *required*
+status checks is configured in the repository's GitHub branch-protection /
+merge-queue settings; the column below reflects merge-queue participation
+declared in the workflows.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 36 12 22
+
+   * - Check (workflow)
+     - What it verifies
+     - Gating
+     - Your action
+   * - `build_and_test_qnx.yml <https://github.com/eclipse-score/reference_integration/blob/main/.github/workflows/build_and_test_qnx.yml>`_
+     - Builds the QNX IFS and runs integration tests on QEMU.
+     - **yes**
+     - none (graph-wide)
+   * - `build_and_test_autosd.yml <https://github.com/eclipse-score/reference_integration/blob/main/.github/workflows/build_and_test_autosd.yml>`_
+     - Builds the AutoSD OCI image with the Automotive Image Builder.
+     - **yes**
+     - none (graph-wide)
+   * - `build_and_test_ebclfsa.yml <https://github.com/eclipse-score/reference_integration/blob/main/.github/workflows/build_and_test_ebclfsa.yml>`_
+     - Builds the EBcLfSA image and runs the high-integrity safety tests.
+     - **yes**
+     - none (graph-wide)
+   * - `known_good_correct.yml <https://github.com/eclipse-score/reference_integration/blob/main/.github/workflows/known_good_correct.yml>`_
+     - Fails if the generated Bazel fragments drift from ``known_good.json``.
+     - **yes**
+     - commit step 1.2 output
+   * - `bzlmod-lock.yml <https://github.com/eclipse-score/reference_integration/blob/main/.github/workflows/bzlmod-lock.yml>`_
+     - Verifies ``MODULE.bazel.lock`` is consistent with the module graph.
+     - **yes**
+     - update lockfile if it fails
+   * - `format.yml <https://github.com/eclipse-score/reference_integration/blob/main/.github/workflows/format.yml>`_
+     - Runs the code-formatting checks.
+     - **yes**
+     - run the format targets
+   * - `codeql-multiple-repo-scan.yml <https://github.com/eclipse-score/reference_integration/blob/main/.github/workflows/codeql-multiple-repo-scan.yml>`_
+     - Multi-repository CodeQL security scan across the integrated modules.
+     - **yes**
+     - none
+   * - `test_and_docs.yml <https://github.com/eclipse-score/reference_integration/blob/main/.github/workflows/test_and_docs.yml>`_
+     - Code-quality checks, builds the docs and reports, publishes to Pages.
+     - **yes**
+     - wire docs in Step 2, reports in Step 7
+   * - `check_release_approvals.yml <https://github.com/eclipse-score/reference_integration/blob/main/.github/workflows/check_release_approvals.yml>`_
+     - Enforces required approvals on PRs targeting ``releases/*`` branches.
+     - release branches only
+     - none
+   * - `build_and_test_linux.yml <https://github.com/eclipse-score/reference_integration/blob/main/.github/workflows/build_and_test_linux.yml>`_
+     - Builds the Linux x86_64 image and runs feature integration tests on Docker.
+     - no
+     - none (graph-wide)
+   * - `internal_tests.yml <https://github.com/eclipse-score/reference_integration/blob/main/.github/workflows/internal_tests.yml>`_
+     - Runs the integration tooling tests (``//scripts/tooling:tooling_tests``).
+     - no
+     - only if you change scripts
+   * - `docs_cleanup.yml <https://github.com/eclipse-score/reference_integration/blob/main/.github/workflows/docs_cleanup.yml>`_
+     - Scheduled cleanup of published documentation versions.
+     - no
+     - none
+   * - `test_integration.yml <https://github.com/eclipse-score/reference_integration/blob/main/.github/workflows/test_integration.yml>`_ /
+       `reusable_smoke-test.yml <https://github.com/eclipse-score/reference_integration/blob/main/.github/workflows/reusable_smoke-test.yml>`_ /
+       `reusable_integration-build.yml <https://github.com/eclipse-score/reference_integration/blob/main/.github/workflows/reusable_integration-build.yml>`_
+     - Smoke-test / reusable build of the latest module ``main`` branches.
+     - no
+     - add runtime targets to
+       `ci/showcase_targets_run.txt <https://github.com/eclipse-score/reference_integration/blob/main/ci/showcase_targets_run.txt>`_
+
+.. _reports:
+
+Reports
+-------
+
+The consolidated outputs published by the integration. They are built by
+``test_and_docs.yml`` and rendered into the documentation site.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 40 30
+
+   * - Report
+     - Contents
+     - Source / target
+   * - Consolidated documentation
+     - All integrated module docs merged into one Sphinx site.
+     - `BUILD <https://github.com/eclipse-score/reference_integration/blob/main/BUILD>`_ ``docs(...)`` → ``bazel run //:docs_combo``
+   * - Platform verification report
+     - Per-release requirements/architecture verification, safety analyses and
+       per-test-case results.
+     - `docs/verification_report/platform_verification_report.rst <https://github.com/eclipse-score/reference_integration/blob/main/docs/verification_report/platform_verification_report.rst>`_
+   * - Unit test summary
+     - Per-module unit-test execution table (generated at build time by
+       ``quality_runners.py``).
+     - `docs/verification_report/unit_test_summary.md <https://github.com/eclipse-score/reference_integration/blob/main/docs/verification_report/unit_test_summary.md>`_
+   * - Coverage summary
+     - Per-module C++ and Rust coverage table (generated at build time by
+       ``quality_runners.py``).
+     - `docs/verification_report/coverage_summary.md <https://github.com/eclipse-score/reference_integration/blob/main/docs/verification_report/coverage_summary.md>`_
+   * - C++ coverage (per module)
+     - lcov/genhtml line/function/branch report for modules declaring ``cpp``.
+     - `scripts/quality_runners.py <https://github.com/eclipse-score/reference_integration/blob/main/scripts/quality_runners.py>`_ →
+       ``python3 scripts/quality_runners.py --modules-to-test <module>``
+   * - Rust coverage reports
+     - Per-module Rust line coverage (C0/C1) for modules declaring ``rust``.
+     - `rust_coverage/BUILD <https://github.com/eclipse-score/reference_integration/blob/main/rust_coverage/BUILD>`_ →
+       ``bazel run //rust_coverage:rust_coverage_<module>``
+   * - Overall feature & process status
+     - Feature/process completion dashboard derived from the pinned module repos.
+     - `docs/s_core_v_1/roadmap/overall_status.rst <https://github.com/eclipse-score/reference_integration/blob/main/docs/s_core_v_1/roadmap/overall_status.rst>`_
+   * - Integration status dashboard
+     - Live build/health overview of the integration.
+     - `status_dashboard.html <https://eclipse-score.github.io/reference_integration/main/status_dashboard.html>`_