fix review findings

Author: antonkri

docs/integration_process/integration_process.rst

@@ -17,7 +17,9 @@ 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** for the first time.
+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
@@ -54,7 +56,12 @@ Before you start, make sure that:
 * 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>//...``).
-* The module builds and tests pass standalone on Linux ``x86_64``.
+* 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).
 

docs/integration_process/reference.rst

@@ -26,7 +26,7 @@ and their images are listed in :ref:`supported_platforms` (Step 4).
 CI checks
 ---------
 
-The pipelines live under `.github/workflows <../../.github/workflows>`_. Most
+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.
 
@@ -46,61 +46,61 @@ declared in the workflows.
      - What it verifies
      - Gating
      - Your action
-   * - `build_and_test_qnx.yml <../../.github/workflows/build_and_test_qnx.yml>`_
+   * - `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 <../../.github/workflows/build_and_test_autosd.yml>`_
+   * - `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 <../../.github/workflows/build_and_test_ebclfsa.yml>`_
+   * - `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 <../../.github/workflows/known_good_correct.yml>`_
+   * - `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 <../../.github/workflows/bzlmod-lock.yml>`_
+   * - `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 <../../.github/workflows/format.yml>`_
+   * - `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 <../../.github/workflows/codeql-multiple-repo-scan.yml>`_
+   * - `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 <../../.github/workflows/test_and_docs.yml>`_
+   * - `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 <../../.github/workflows/check_release_approvals.yml>`_
+   * - `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 <../../.github/workflows/build_and_test_linux.yml>`_
+   * - `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 <../../.github/workflows/internal_tests.yml>`_
+   * - `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 <../../.github/workflows/docs_cleanup.yml>`_
+   * - `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 <../../.github/workflows/test_integration.yml>`_ /
-       `reusable_smoke-test.yml <../../.github/workflows/reusable_smoke-test.yml>`_ /
-       `reusable_integration-build.yml <../../.github/workflows/reusable_integration-build.yml>`_
+   * - `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 <../../ci/showcase_targets_run.txt>`_
+       `ci/showcase_targets_run.txt <https://github.com/eclipse-score/reference_integration/blob/main/ci/showcase_targets_run.txt>`_
 
 .. _reports:
 
@@ -119,30 +119,30 @@ The consolidated outputs published by the integration. They are built by
      - Source / target
    * - Consolidated documentation
      - All integrated module docs merged into one Sphinx site.
-     - `BUILD <../../BUILD>`_ ``docs(...)`` → ``bazel run //:docs_combo``
+     - `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 <../../docs/verification_report/platform_verification_report.rst>`_
+     - `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 <../../docs/verification_report/unit_test_summary.md>`_
+     - `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 <../../docs/verification_report/coverage_summary.md>`_
+     - `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 <../../scripts/quality_runners.py>`_ →
+     - `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 <../../rust_coverage/BUILD>`_ →
+     - `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 <../../docs/s_core_v_1/roadmap/overall_status.rst>`_
+     - `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>`_

docs/integration_process/step_1_add_module.rst

@@ -15,10 +15,13 @@
 Step 1 — Adding module to reference integration
 =================================================
 
-   **What this unlocks:** your module becomes a *known* part of the integration,
-   pinned at an exact commit, enters the **Bazel module graph** and builds
-   cleanly against every other module. This is the foundation every later step
-   builds on — afterwards ``@score_my_module//...`` resolves and any other
+.. admonition:: What it unlocks
+   :class: tip
+
+   **Module in the graph** — Your module becomes a *known* part of the
+   integration, pinned at an exact commit, enters the **Bazel module graph** and
+   builds cleanly against every other module. This is the foundation every later
+   step builds on — afterwards ``@score_my_module//...`` resolves and any other
    target can depend on your module.
 
 1.1 Register the module in ``known_good.json``
@@ -28,7 +31,7 @@ Step 1 — Adding module to reference integration
 which commit — are part of the integration. Every other generated file is
 derived from it, so this is always the first change.
 
-Open `known_good.json <../../known_good.json>`_. It has two top-level groups
+Open `known_good.json <https://github.com/eclipse-score/reference_integration/blob/main/known_good.json>`_. It has two top-level groups
 under ``modules``:
 
 * ``target_sw`` — the S-CORE software modules that are built and shipped
@@ -114,14 +117,28 @@ hand. After editing the JSON, regenerate them:
 
 This (re)writes:
 
-* `bazel_common/score_modules_target_sw.MODULE.bazel <../../bazel_common/score_modules_target_sw.MODULE.bazel>`_
+* `bazel_common/score_modules_target_sw.MODULE.bazel <https://github.com/eclipse-score/reference_integration/blob/main/bazel_common/score_modules_target_sw.MODULE.bazel>`_
   — a ``bazel_dep`` + ``git_override`` block for your module. This file is
   pulled into the build via ``include(...)`` in
-  `MODULE.bazel <../../MODULE.bazel>`_.
-* `rust_coverage/BUILD <../../rust_coverage/BUILD>`_ — a
+  `MODULE.bazel <https://github.com/eclipse-score/reference_integration/blob/main/MODULE.bazel>`_.
+* `rust_coverage/BUILD <https://github.com/eclipse-score/reference_integration/blob/main/rust_coverage/BUILD>`_ — a
   ``rust_coverage_report`` target for every module that declares ``rust`` in its
   ``langs`` (skipped for C++-only modules).
 
+Next, refresh the Bazel lockfile so it reflects the updated module graph:
+
+.. code-block:: bash
+
+   bazel mod deps --lockfile_mode=update
+
+Adding your module introduces a new ``bazel_dep`` / ``git_override`` into the
+module graph, which changes the set of resolved dependencies. Running ``bazel
+mod deps`` with ``--lockfile_mode=update`` re-resolves the graph and writes the
+new dependencies into `MODULE.bazel.lock <https://github.com/eclipse-score/reference_integration/blob/main/MODULE.bazel.lock>`_. Committing
+an up-to-date lockfile keeps the dependency resolution reproducible for everyone
+and is required by the ``Bzlmod Lockfile Check`` CI job (see section 1.4), which
+fails if the committed lockfile is out of sync with the module graph.
+
 Commit the regenerated files together with the ``known_good.json`` change. CI
 verifies that the generated files are in sync with the JSON (see the
 ``known_good_correct`` workflow), so a manual edit that drifts from the JSON
@@ -135,9 +152,17 @@ will fail.
 If the module does not build cleanly out-of-tree (e.g. label visibility issues),
 add patch files under ``patches/<module>/`` and reference them from the
 ``bazel_patches`` list of the module entry in ``known_good.json``. See
-`patches/communication <../../patches/communication>`_ for a worked example. The
+`patches/communication <https://github.com/eclipse-score/reference_integration/tree/main/patches/communication>`_ for a worked example. The
 generator emits ``patches = [...]`` with ``patch_strip = 1`` automatically.
 
+.. note::
+
+   Patching a module should be the **exception, not the rule**. A patch keeps a
+   local divergence from the upstream module that has to be maintained and
+   re-based on every update. Prefer fixing the underlying issue in the module's
+   own repository so it builds cleanly out-of-tree, and only reach for a patch
+   as a temporary, last-resort workaround.
+
 1.4 CI checks that the module was added correctly
 -------------------------------------------------
 
@@ -153,14 +178,14 @@ check that the generated metadata is in sync with ``known_good.json``:
      - What it verifies
      - Fix if it fails
    * - Known Good Matches Bazel
-       (`known_good_correct.yml <../../.github/workflows/known_good_correct.yml>`_)
+       (`known_good_correct.yml <https://github.com/eclipse-score/reference_integration/blob/main/.github/workflows/known_good_correct.yml>`_)
      - Re-runs ``update_module_from_known_good.py`` and fails if the generated
        Bazel fragments differ from what you committed — i.e. ``known_good.json``
        and the generated ``*.MODULE.bazel`` / ``rust_coverage/BUILD`` are out of
        sync.
      - re-run step 1.2 and commit the regenerated files
    * - Bzlmod Lockfile Check
-       (`bzlmod-lock.yml <../../.github/workflows/bzlmod-lock.yml>`_)
+       (`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 updated module
        graph (your new ``bazel_dep`` / ``git_override``).
      - refresh and commit ``MODULE.bazel.lock``

docs/integration_process/step_2_documentation.rst

@@ -15,17 +15,20 @@
 Step 2 — Join the documentation and process-compliance checks
 =============================================================
 
-   **What this unlocks:** your module's documentation appears in the single,
-   combined docs site that is built and published for the whole integration —
-   and, just as importantly, your module's **requirements, architecture and
-   other process artifacts are validated against the S-CORE process** as part of
-   the same build. This is usually the first thing you *extend the integration
-   with* after the module is in the graph.
+.. admonition:: What it unlocks
+   :class: tip
+
+   **Docs & process checks** — Your module's documentation appears in the
+   single, combined docs site that is built and published for the whole
+   integration — and, just as importantly, your module's **requirements,
+   architecture and other process artifacts are validated against the S-CORE
+   process** as part of the same build. This is usually the first thing you
+   *extend the integration with* after the module is in the graph.
 
 Building the docs is not only about rendering pages. The integration uses the
 docs-as-code toolchain (`score_docs_as_code
 <https://github.com/eclipse-score/docs-as-code>`_, pulled in via
-``score_sphinx_bundle`` in `docs/conf.py <../../docs/conf.py>`_), which runs the
+``score_sphinx_bundle`` in `docs/conf.py <https://github.com/eclipse-score/reference_integration/blob/main/docs/conf.py>`_), which runs the
 **S-CORE metamodel checks** on every ``needs`` object: requirements,
 architecture elements, safety artifacts and their links must conform to the
 process model defined in `score_process
@@ -38,7 +41,7 @@ The integration builds one Sphinx site that merges the docs of every integrated
 module. To pull yours in:
 
 #. Add your module's ``needs_json`` to the ``docs(...)`` rule's ``data`` list in
-   the top-level `BUILD <../../BUILD>`_ file:
+   the top-level `BUILD <https://github.com/eclipse-score/reference_integration/blob/main/BUILD>`_ file:
 
    .. code-block:: python
 
@@ -67,18 +70,18 @@ module. To pull yours in:
         - Page to edit
         - Put your module here if it is…
       * - **Modules**
-        - `docs/sw_components.rst <../../docs/sw_components.rst>`_
+        - `docs/sw_components.rst <https://github.com/eclipse-score/reference_integration/blob/main/docs/sw_components.rst>`_
         - an S-CORE **software module** that ships in the integration — i.e. it
           lives under ``modules.target_sw`` in ``known_good.json`` (communication,
           persistency, logging, orchestrator, baselibs, …). This is the common
           case.
       * - **Process, Methods & Tools**
-        - `docs/process_methods_tools.rst <../../docs/process_methods_tools.rst>`_
+        - `docs/process_methods_tools.rst <https://github.com/eclipse-score/reference_integration/blob/main/docs/process_methods_tools.rst>`_
         - a **tooling / process** repo from ``modules.tooling`` (platform, process,
           docs-as-code) rather than a shipped software module.
 
    For a normal software module, add the entry to the ``Modules`` toctree in
-   `docs/sw_components.rst <../../docs/sw_components.rst>`_, next to the existing
+   `docs/sw_components.rst <https://github.com/eclipse-score/reference_integration/blob/main/docs/sw_components.rst>`_, next to the existing
    modules:
 
    .. code-block:: rst
@@ -124,7 +127,7 @@ The docs are built and published by the ``test_and_docs`` workflow (see
    **Planned refactoring.** Today documentation generation is entangled with
    unit tests, coverage and feature integration tests in the single
    ``test_and_docs`` workflow
-   (`test_and_docs.yml <../../.github/workflows/test_and_docs.yml>`_). This
+   (`test_and_docs.yml <https://github.com/eclipse-score/reference_integration/blob/main/.github/workflows/test_and_docs.yml>`_). This
    should be refactored: the documentation build (including the metamodel /
    process-compliance checks) belongs in a **dedicated, reusable workflow shared
    across all S-CORE repositories**, hosted centrally in the