Skip to content

Commit c03f9bd

Browse files
antonkriantonkri
committed
WIP: Add integration process documentation
Add step-by-step integration process documentation including module addition, documentation, unit tests, platforms, component tests, integration tests, reporting, and code quality steps, plus a checklist and reference.
1 parent 2fc07d9 commit c03f9bd

11 files changed

Lines changed: 1147 additions & 0 deletions

‎docs/integration_process/checklist.rst‎

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

‎docs/integration_process/integration_process.rst‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,5 +12,70 @@
1212
# SPDX-License-Identifier: Apache-2.0
1313
# *******************************************************************************
1414
15+
###################
1516
Integration Process
1617
###################
18+
19+
This document is a step-by-step *how-to* for module owners who want to integrate
20+
their own S-CORE module into the **Reference Integration** for the first time.
21+
22+
It walks you through everything from registering the module in
23+
``known_good.json`` over wiring it into the Bazel build, the showcases, the
24+
images and the CLI, up to adding it to the CI/CD pipelines and the consolidated
25+
reporting (documentation, coverage and verification reports).
26+
27+
28+
What "integration" means here
29+
=============================
30+
31+
The Reference Integration is a single `Bazel (bzlmod) <https://bazel.build/external/overview#bzlmod>`_
32+
build that pulls every S-CORE module together at a defined commit, builds them
33+
against each other and runs their tests, showcases and reports.
34+
35+
Integrating a module is **incremental**: each step below builds on the previous
36+
one and *extends the reach* of your module a little further into the
37+
integration. You climb the ladder only as far as your module needs — a pure
38+
library may stop after it builds in-tree, while a module with a runnable example
39+
goes all the way to running on every target platform and being exercised by
40+
integration tests.
41+
42+
The chapters that follow walk this ladder in order. Stop at whatever rung makes
43+
sense for your module.
44+
45+
46+
Prerequisites
47+
=============
48+
49+
Before you start, make sure that:
50+
51+
* Your module lives in its own GitHub repository under the ``eclipse-score``
52+
organization and is a **bzlmod module**, i.e. it has a top-level
53+
``MODULE.bazel`` with a ``module(name = "score_<your_module>")`` declaration.
54+
* The module name follows the ``score_<name>`` convention (e.g.
55+
``score_communication``). The same name is used as the Bazel
56+
``bazel_dep`` / repository name (``@score_<name>//...``).
57+
* The module builds and tests pass standalone on Linux ``x86_64``.
58+
* You know the commit hash you want to pin (the integration always pins an exact
59+
commit, never a floating branch).
60+
61+
62+
The integration steps
63+
======================
64+
65+
Work through the chapters in order — each one extends the reach of your module a
66+
little further into the integration:
67+
68+
.. toctree::
69+
:maxdepth: 2
70+
:numbered:
71+
72+
step_1_add_module
73+
step_2_documentation
74+
step_3_unit_tests
75+
step_4_platforms
76+
step_5_component_tests
77+
step_6_integration_tests
78+
step_7_reporting
79+
step_8_code_quality
80+
checklist
81+
reference

‎docs/integration_process/reference.rst‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
..
2+
# *******************************************************************************
3+
# Copyright (c) 2026 Contributors to the Eclipse Foundation
4+
#
5+
# See the NOTICE file(s) distributed with this work for additional
6+
# information regarding copyright ownership.
7+
#
8+
# This program and the accompanying materials are made available under the
9+
# terms of the Apache License Version 2.0 which is available at
10+
# https://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# SPDX-License-Identifier: Apache-2.0
13+
# *******************************************************************************
14+
15+
Reference
16+
=========
17+
18+
This section is a catalogue of *what already exists* in the integration — the
19+
CI checks that run on every change and the consolidated reports — together with
20+
the touch-point a new module has in each. Use it to understand where your module
21+
shows up once it is wired in via the steps above. The supported target platforms
22+
and their images are listed in :ref:`supported_platforms` (Step 4).
23+
24+
.. _ci_checks:
25+
26+
CI checks
27+
---------
28+
29+
The pipelines live under `.github/workflows <../../.github/workflows>`_. Most
30+
operate on ``//...`` and pick up your module without changes; the table says
31+
what each check verifies and whether you typically need to touch anything.
32+
33+
**Gating** marks the checks that run in the merge queue
34+
(``merge_group``) and must therefore be green before a pull request can be
35+
merged. The remaining checks are informational, run only on ``push``/schedule,
36+
or gate a different event (release approvals). The definitive list of *required*
37+
status checks is configured in the repository's GitHub branch-protection /
38+
merge-queue settings; the column below reflects merge-queue participation
39+
declared in the workflows.
40+
41+
.. list-table::
42+
:header-rows: 1
43+
:widths: 30 36 12 22
44+
45+
* - Check (workflow)
46+
- What it verifies
47+
- Gating
48+
- Your action
49+
* - `build_and_test_qnx.yml <../../.github/workflows/build_and_test_qnx.yml>`_
50+
- Builds the QNX IFS and runs integration tests on QEMU.
51+
- **yes**
52+
- none (graph-wide)
53+
* - `build_and_test_autosd.yml <../../.github/workflows/build_and_test_autosd.yml>`_
54+
- Builds the AutoSD OCI image with the Automotive Image Builder.
55+
- **yes**
56+
- none (graph-wide)
57+
* - `build_and_test_ebclfsa.yml <../../.github/workflows/build_and_test_ebclfsa.yml>`_
58+
- Builds the EBcLfSA image and runs the high-integrity safety tests.
59+
- **yes**
60+
- none (graph-wide)
61+
* - `known_good_correct.yml <../../.github/workflows/known_good_correct.yml>`_
62+
- Fails if the generated Bazel fragments drift from ``known_good.json``.
63+
- **yes**
64+
- commit step 1.2 output
65+
* - `bzlmod-lock.yml <../../.github/workflows/bzlmod-lock.yml>`_
66+
- Verifies ``MODULE.bazel.lock`` is consistent with the module graph.
67+
- **yes**
68+
- update lockfile if it fails
69+
* - `format.yml <../../.github/workflows/format.yml>`_
70+
- Runs the code-formatting checks.
71+
- **yes**
72+
- run the format targets
73+
* - `codeql-multiple-repo-scan.yml <../../.github/workflows/codeql-multiple-repo-scan.yml>`_
74+
- Multi-repository CodeQL security scan across the integrated modules.
75+
- **yes**
76+
- none
77+
* - `test_and_docs.yml <../../.github/workflows/test_and_docs.yml>`_
78+
- Code-quality checks, builds the docs and reports, publishes to Pages.
79+
- **yes**
80+
- wire docs in Step 2, reports in Step 7
81+
* - `check_release_approvals.yml <../../.github/workflows/check_release_approvals.yml>`_
82+
- Enforces required approvals on PRs targeting ``releases/*`` branches.
83+
- release branches only
84+
- none
85+
* - `build_and_test_linux.yml <../../.github/workflows/build_and_test_linux.yml>`_
86+
- Builds the Linux x86_64 image and runs feature integration tests on Docker.
87+
- no
88+
- none (graph-wide)
89+
* - `internal_tests.yml <../../.github/workflows/internal_tests.yml>`_
90+
- Runs the integration tooling tests (``//scripts/tooling:tooling_tests``).
91+
- no
92+
- only if you change scripts
93+
* - `docs_cleanup.yml <../../.github/workflows/docs_cleanup.yml>`_
94+
- Scheduled cleanup of published documentation versions.
95+
- no
96+
- none
97+
* - `test_integration.yml <../../.github/workflows/test_integration.yml>`_ /
98+
`reusable_smoke-test.yml <../../.github/workflows/reusable_smoke-test.yml>`_ /
99+
`reusable_integration-build.yml <../../.github/workflows/reusable_integration-build.yml>`_
100+
- Smoke-test / reusable build of the latest module ``main`` branches.
101+
- no
102+
- add runtime targets to
103+
`ci/showcase_targets_run.txt <../../ci/showcase_targets_run.txt>`_
104+
105+
.. _reports:
106+
107+
Reports
108+
-------
109+
110+
The consolidated outputs published by the integration. They are built by
111+
``test_and_docs.yml`` and rendered into the documentation site.
112+
113+
.. list-table::
114+
:header-rows: 1
115+
:widths: 30 40 30
116+
117+
* - Report
118+
- Contents
119+
- Source / target
120+
* - Consolidated documentation
121+
- All integrated module docs merged into one Sphinx site.
122+
- `BUILD <../../BUILD>`_ ``docs(...)`` → ``bazel run //:docs_combo``
123+
* - Platform verification report
124+
- Per-release requirements/architecture verification, safety analyses and
125+
per-test-case results.
126+
- `docs/verification_report/platform_verification_report.rst <../../docs/verification_report/platform_verification_report.rst>`_
127+
* - Unit test summary
128+
- Per-module unit-test execution table (generated at build time by
129+
``quality_runners.py``).
130+
- `docs/verification_report/unit_test_summary.md <../../docs/verification_report/unit_test_summary.md>`_
131+
* - Coverage summary
132+
- Per-module C++ and Rust coverage table (generated at build time by
133+
``quality_runners.py``).
134+
- `docs/verification_report/coverage_summary.md <../../docs/verification_report/coverage_summary.md>`_
135+
* - C++ coverage (per module)
136+
- lcov/genhtml line/function/branch report for modules declaring ``cpp``.
137+
- `scripts/quality_runners.py <../../scripts/quality_runners.py>`_ →
138+
``python3 scripts/quality_runners.py --modules-to-test <module>``
139+
* - Rust coverage reports
140+
- Per-module Rust line coverage (C0/C1) for modules declaring ``rust``.
141+
- `rust_coverage/BUILD <../../rust_coverage/BUILD>`_ →
142+
``bazel run //rust_coverage:rust_coverage_<module>``
143+
* - Overall feature & process status
144+
- Feature/process completion dashboard derived from the pinned module repos.
145+
- `docs/s_core_v_1/roadmap/overall_status.rst <../../docs/s_core_v_1/roadmap/overall_status.rst>`_
146+
* - Integration status dashboard
147+
- Live build/health overview of the integration.
148+
- `status_dashboard.html <https://eclipse-score.github.io/reference_integration/main/status_dashboard.html>`_

0 commit comments

Comments
 (0)