From 97767df2e43ccdae59b5378b0c280058d4e8b3f6 Mon Sep 17 00:00:00 2001 From: Gabriel Pinheiro Date: Fri, 28 Aug 2026 10:42:23 +0100 Subject: [PATCH 1/9] docs: add component requirements for all 7 components --- BUILD | 29 ++++++++++++++- score/config/docs/BUILD | 22 +++++++++++ score/config/docs/index.rst | 36 ++++++++++++++++++ score/config/docs/requirements/index.rst | 20 ++++++++++ .../config/docs/requirements/requirements.rst | 34 +++++++++++++++++ score/gateway_ipc_binding/docs/index.rst | 13 ++++++- .../docs/requirements/index.rst | 20 ++++++++++ .../docs/requirements/requirements.rst | 37 +++++++++++++++++++ score/gatewayd/docs/BUILD | 22 +++++++++++ score/gatewayd/docs/index.rst | 28 ++++++++++++++ score/gatewayd/docs/requirements/index.rst | 20 ++++++++++ .../docs/requirements/requirements.rst | 36 ++++++++++++++++++ score/serializer/docs/BUILD | 22 +++++++++++ score/serializer/docs/index.rst | 28 ++++++++++++++ score/serializer/docs/requirements/index.rst | 20 ++++++++++ .../docs/requirements/requirements.rst | 35 ++++++++++++++++++ score/socom/docs/index.rst | 13 ++++++- score/socom/docs/requirements/index.rst | 20 ++++++++++ .../socom/docs/requirements/requirements.rst | 36 ++++++++++++++++++ score/someip/docs/BUILD | 22 +++++++++++ score/someip/docs/index.rst | 36 ++++++++++++++++++ score/someip/docs/requirements/index.rst | 20 ++++++++++ .../someip/docs/requirements/requirements.rst | 36 ++++++++++++++++++ score/someipd/docs/BUILD | 22 +++++++++++ score/someipd/docs/index.rst | 28 ++++++++++++++ score/someipd/docs/requirements/index.rst | 20 ++++++++++ .../docs/requirements/requirements.rst | 36 ++++++++++++++++++ 27 files changed, 707 insertions(+), 4 deletions(-) create mode 100644 score/config/docs/BUILD create mode 100644 score/config/docs/index.rst create mode 100644 score/config/docs/requirements/index.rst create mode 100644 score/config/docs/requirements/requirements.rst create mode 100644 score/gateway_ipc_binding/docs/requirements/index.rst create mode 100644 score/gateway_ipc_binding/docs/requirements/requirements.rst create mode 100644 score/gatewayd/docs/BUILD create mode 100644 score/gatewayd/docs/index.rst create mode 100644 score/gatewayd/docs/requirements/index.rst create mode 100644 score/gatewayd/docs/requirements/requirements.rst create mode 100644 score/serializer/docs/BUILD create mode 100644 score/serializer/docs/index.rst create mode 100644 score/serializer/docs/requirements/index.rst create mode 100644 score/serializer/docs/requirements/requirements.rst create mode 100644 score/socom/docs/requirements/index.rst create mode 100644 score/socom/docs/requirements/requirements.rst create mode 100644 score/someip/docs/BUILD create mode 100644 score/someip/docs/index.rst create mode 100644 score/someip/docs/requirements/index.rst create mode 100644 score/someip/docs/requirements/requirements.rst create mode 100644 score/someipd/docs/BUILD create mode 100644 score/someipd/docs/index.rst create mode 100644 score/someipd/docs/requirements/index.rst create mode 100644 score/someipd/docs/requirements/requirements.rst diff --git a/BUILD b/BUILD index 7da04aacc..4eb6e9255 100644 --- a/BUILD +++ b/BUILD @@ -38,8 +38,8 @@ use_format_targets( docs( bundles = [ { - "bundle": "//score/socom/docs:docs_bundle", - "mount_at": "socom", + "bundle": "//score/config/docs:docs_bundle", + "mount_at": "config", "attach_to": "components", }, { @@ -47,6 +47,31 @@ docs( "mount_at": "gateway_ipc_binding", "attach_to": "components", }, + { + "bundle": "//score/gatewayd/docs:docs_bundle", + "mount_at": "gatewayd", + "attach_to": "components", + }, + { + "bundle": "//score/serializer/docs:docs_bundle", + "mount_at": "serializer", + "attach_to": "components", + }, + { + "bundle": "//score/socom/docs:docs_bundle", + "mount_at": "socom", + "attach_to": "components", + }, + { + "bundle": "//score/someip/docs:docs_bundle", + "mount_at": "someip", + "attach_to": "components", + }, + { + "bundle": "//score/someipd/docs:docs_bundle", + "mount_at": "someipd", + "attach_to": "components", + }, ], source_dir = "docs", ) diff --git a/score/config/docs/BUILD b/score/config/docs/BUILD new file mode 100644 index 000000000..8468d3310 --- /dev/null +++ b/score/config/docs/BUILD @@ -0,0 +1,22 @@ +# ******************************************************************************* +# 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 +# ******************************************************************************* + +load("@score_docs_as_code//:docs.bzl", "docs_bundle") + +# Docs bundle for this component. Kept in its own package so the parent +# BUILD does not need to load @score_docs_as_code. +docs_bundle( + name = "docs_bundle", + source_dir = "", + visibility = ["//visibility:public"], +) diff --git a/score/config/docs/index.rst b/score/config/docs/index.rst new file mode 100644 index 000000000..8b99a507e --- /dev/null +++ b/score/config/docs/index.rst @@ -0,0 +1,36 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _config: + +Config +###### + +.. comp:: Config + :id: comp__config + :security: NO + :safety: QM + :status: valid + :version: 1 + :belongs_to: feat__someip_gateway + +Abstract +======== + +Provides the FlatBuffers schema (mw_someip_config.fbs) and JSON schema used to define and validate gateway configuration. + +.. toctree:: + :maxdepth: 1 + + requirements/index diff --git a/score/config/docs/requirements/index.rst b/score/config/docs/requirements/index.rst new file mode 100644 index 000000000..7ae4968c8 --- /dev/null +++ b/score/config/docs/requirements/index.rst @@ -0,0 +1,20 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +############ + +.. toctree:: + + requirements diff --git a/score/config/docs/requirements/requirements.rst b/score/config/docs/requirements/requirements.rst new file mode 100644 index 000000000..89af113cd --- /dev/null +++ b/score/config/docs/requirements/requirements.rst @@ -0,0 +1,34 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Component Config Requirements +############################# + +Functional Requirements +----------------------- + +.. comp_req:: FlatBuffers gateway configuration schema + :id: comp_req__config__flatbuffer_schema + :reqtype: Interface + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__config + + The gateway configuration shall be defined as a FlatBuffers schema + (``mw_someip_config.fbs``) together with a JSON schema + (``mw_someip_config.schema.json``) so both binary and JSON forms of + the configuration can be validated against a single source of truth. + diff --git a/score/gateway_ipc_binding/docs/index.rst b/score/gateway_ipc_binding/docs/index.rst index c8cb7415c..59d5b5651 100644 --- a/score/gateway_ipc_binding/docs/index.rst +++ b/score/gateway_ipc_binding/docs/index.rst @@ -12,8 +12,18 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +.. _gateway_ipc_binding: + Gateway IPC Binding -=================== +################### + +.. comp:: Gateway IPC Binding + :id: comp__gateway_ipc_binding + :security: NO + :safety: QM + :status: valid + :version: 1 + :belongs_to: feat__someip_gateway Gateway IPC Binding bridges SOCom service discovery and event transport across a local IPC link. It combines: @@ -122,3 +132,4 @@ Further details shared_memory ipc_protocol + requirements/index diff --git a/score/gateway_ipc_binding/docs/requirements/index.rst b/score/gateway_ipc_binding/docs/requirements/index.rst new file mode 100644 index 000000000..7ae4968c8 --- /dev/null +++ b/score/gateway_ipc_binding/docs/requirements/index.rst @@ -0,0 +1,20 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +############ + +.. toctree:: + + requirements diff --git a/score/gateway_ipc_binding/docs/requirements/requirements.rst b/score/gateway_ipc_binding/docs/requirements/requirements.rst new file mode 100644 index 000000000..eac79b514 --- /dev/null +++ b/score/gateway_ipc_binding/docs/requirements/requirements.rst @@ -0,0 +1,37 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Component Gateway IPC Binding Requirements +########################################## + +Functional Requirements +----------------------- + +.. comp_req:: Symmetric IPC binding with split control and payload planes + :id: comp_req__gateway_ipc_binding__ctrl_chan + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__gateway_ipc_binding + + The gateway IPC binding shall establish a symmetric client/server + control channel over ``score::message_passing`` and, once + established, allow either peer to offer services, request services, + subscribe to events, and publish event updates. Event payloads + shall travel through per-service shared-memory segments rather than + the control channel, referenced by a ``Shared_memory_handle`` and + released via ``Payload_consumed``. + diff --git a/score/gatewayd/docs/BUILD b/score/gatewayd/docs/BUILD new file mode 100644 index 000000000..8468d3310 --- /dev/null +++ b/score/gatewayd/docs/BUILD @@ -0,0 +1,22 @@ +# ******************************************************************************* +# 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 +# ******************************************************************************* + +load("@score_docs_as_code//:docs.bzl", "docs_bundle") + +# Docs bundle for this component. Kept in its own package so the parent +# BUILD does not need to load @score_docs_as_code. +docs_bundle( + name = "docs_bundle", + source_dir = "", + visibility = ["//visibility:public"], +) diff --git a/score/gatewayd/docs/index.rst b/score/gatewayd/docs/index.rst new file mode 100644 index 000000000..3af4635da --- /dev/null +++ b/score/gatewayd/docs/index.rst @@ -0,0 +1,28 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _gatewayd: + +gatewayd +######## + +Abstract +======== + +The gateway daemon. Bridges local IPC service instances with remote SOME/IP service instances across the ASIL boundary, handling service offers, requests, event subscriptions, and payload transfer. + +.. toctree:: + :maxdepth: 1 + + requirements/index diff --git a/score/gatewayd/docs/requirements/index.rst b/score/gatewayd/docs/requirements/index.rst new file mode 100644 index 000000000..7ae4968c8 --- /dev/null +++ b/score/gatewayd/docs/requirements/index.rst @@ -0,0 +1,20 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +############ + +.. toctree:: + + requirements diff --git a/score/gatewayd/docs/requirements/requirements.rst b/score/gatewayd/docs/requirements/requirements.rst new file mode 100644 index 000000000..582172e3b --- /dev/null +++ b/score/gatewayd/docs/requirements/requirements.rst @@ -0,0 +1,36 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Component gatewayd Requirements +############################### + +Functional Requirements +----------------------- + +.. comp_req:: Bridge local IPC and remote SOME/IP service instances + :id: comp_req__gatewayd__local_remote_bridging + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__gatewayd + + ``gatewayd`` shall present local IPC service instances + (``LocalServiceInstance``) and remote SOME/IP service instances + (``RemoteServiceInstance``) to SOCom and shall forward service + offers, requests, event subscriptions and event updates between the + two sides so that an application client is unaware of the transport + layer. + diff --git a/score/serializer/docs/BUILD b/score/serializer/docs/BUILD new file mode 100644 index 000000000..8468d3310 --- /dev/null +++ b/score/serializer/docs/BUILD @@ -0,0 +1,22 @@ +# ******************************************************************************* +# 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 +# ******************************************************************************* + +load("@score_docs_as_code//:docs.bzl", "docs_bundle") + +# Docs bundle for this component. Kept in its own package so the parent +# BUILD does not need to load @score_docs_as_code. +docs_bundle( + name = "docs_bundle", + source_dir = "", + visibility = ["//visibility:public"], +) diff --git a/score/serializer/docs/index.rst b/score/serializer/docs/index.rst new file mode 100644 index 000000000..f0bde7a5e --- /dev/null +++ b/score/serializer/docs/index.rst @@ -0,0 +1,28 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _serializer: + +Serializer +########## + +Abstract +======== + +Serialization utilities. Currently provides a null-passthrough serializer for pre-serialized payloads so the fast path avoids double serialization. + +.. toctree:: + :maxdepth: 1 + + requirements/index diff --git a/score/serializer/docs/requirements/index.rst b/score/serializer/docs/requirements/index.rst new file mode 100644 index 000000000..7ae4968c8 --- /dev/null +++ b/score/serializer/docs/requirements/index.rst @@ -0,0 +1,20 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +############ + +.. toctree:: + + requirements diff --git a/score/serializer/docs/requirements/requirements.rst b/score/serializer/docs/requirements/requirements.rst new file mode 100644 index 000000000..4857099a1 --- /dev/null +++ b/score/serializer/docs/requirements/requirements.rst @@ -0,0 +1,35 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Component Serializer Requirements +################################# + +Functional Requirements +----------------------- + +.. comp_req:: Null-passthrough serializer for pre-serialized payloads + :id: comp_req__serializer__null_passthrough + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__serializer + + The serializer shall provide a null-passthrough implementation + (``NullSerializer``) for payloads that arrive already serialized + (``PreSerializedData``), so the fast path can avoid a second + serialization pass while still satisfying the generic + ``Serializer`` interface. + diff --git a/score/socom/docs/index.rst b/score/socom/docs/index.rst index 126524334..2423bd23c 100644 --- a/score/socom/docs/index.rst +++ b/score/socom/docs/index.rst @@ -12,8 +12,18 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +.. _socom: + SOCom -===== +##### + +.. comp:: SOCom + :id: comp__socom + :security: NO + :safety: QM + :status: valid + :version: 1 + :belongs_to: feat__someip_gateway The SOCom (Service-Oriented Communication) library provides the middleware abstraction layer for SOME/IP communication in the S-CORE framework. @@ -22,3 +32,4 @@ abstraction layer for SOME/IP communication in the S-CORE framework. :maxdepth: 1 design/index + requirements/index diff --git a/score/socom/docs/requirements/index.rst b/score/socom/docs/requirements/index.rst new file mode 100644 index 000000000..7ae4968c8 --- /dev/null +++ b/score/socom/docs/requirements/index.rst @@ -0,0 +1,20 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +############ + +.. toctree:: + + requirements diff --git a/score/socom/docs/requirements/requirements.rst b/score/socom/docs/requirements/requirements.rst new file mode 100644 index 000000000..ca054f8f7 --- /dev/null +++ b/score/socom/docs/requirements/requirements.rst @@ -0,0 +1,36 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Component SOCom Requirements +############################ + +Functional Requirements +----------------------- + +.. comp_req:: Service-oriented communication runtime + :id: comp_req__socom__service_runtime + :reqtype: Interface + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__socom + + SOCom shall expose ``Runtime``, ``ClientConnector`` and + ``ServerConnector`` APIs so that services can be offered, requested, + subscribed to, and their event/method payloads exchanged through a + pluggable transport backend (gateway IPC binding, mock, or any + future backend) without exposing the transport details to the + application. + diff --git a/score/someip/docs/BUILD b/score/someip/docs/BUILD new file mode 100644 index 000000000..8468d3310 --- /dev/null +++ b/score/someip/docs/BUILD @@ -0,0 +1,22 @@ +# ******************************************************************************* +# 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 +# ******************************************************************************* + +load("@score_docs_as_code//:docs.bzl", "docs_bundle") + +# Docs bundle for this component. Kept in its own package so the parent +# BUILD does not need to load @score_docs_as_code. +docs_bundle( + name = "docs_bundle", + source_dir = "", + visibility = ["//visibility:public"], +) diff --git a/score/someip/docs/index.rst b/score/someip/docs/index.rst new file mode 100644 index 000000000..31a5c3f3b --- /dev/null +++ b/score/someip/docs/index.rst @@ -0,0 +1,36 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _someip: + +someip +###### + +.. comp:: someip + :id: comp__someip + :security: NO + :safety: QM + :status: valid + :version: 1 + :belongs_to: feat__someip_gateway + +Abstract +======== + +SOME/IP protocol type and constant definitions (message header fields, method/event IDs, error codes) per the Open SOME/IP protocol specification. + +.. toctree:: + :maxdepth: 1 + + requirements/index diff --git a/score/someip/docs/requirements/index.rst b/score/someip/docs/requirements/index.rst new file mode 100644 index 000000000..7ae4968c8 --- /dev/null +++ b/score/someip/docs/requirements/index.rst @@ -0,0 +1,20 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +############ + +.. toctree:: + + requirements diff --git a/score/someip/docs/requirements/requirements.rst b/score/someip/docs/requirements/requirements.rst new file mode 100644 index 000000000..5fffb43ae --- /dev/null +++ b/score/someip/docs/requirements/requirements.rst @@ -0,0 +1,36 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Component someip Requirements +############################# + +Functional Requirements +----------------------- + +.. comp_req:: SOME/IP protocol type and constant definitions + :id: comp_req__someip__protocol_types + :reqtype: Interface + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__someip + + The ``someip`` library shall provide the header field types + (``types.h``), protocol constants (``constants.h``) and error codes + (``someip_error.h``) required by the Open SOME/IP protocol + specification, so that downstream components (``someipd``, + ``gatewayd``) share a single canonical definition of the on-wire + protocol elements. + diff --git a/score/someipd/docs/BUILD b/score/someipd/docs/BUILD new file mode 100644 index 000000000..8468d3310 --- /dev/null +++ b/score/someipd/docs/BUILD @@ -0,0 +1,22 @@ +# ******************************************************************************* +# 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 +# ******************************************************************************* + +load("@score_docs_as_code//:docs.bzl", "docs_bundle") + +# Docs bundle for this component. Kept in its own package so the parent +# BUILD does not need to load @score_docs_as_code. +docs_bundle( + name = "docs_bundle", + source_dir = "", + visibility = ["//visibility:public"], +) diff --git a/score/someipd/docs/index.rst b/score/someipd/docs/index.rst new file mode 100644 index 000000000..7d8255d31 --- /dev/null +++ b/score/someipd/docs/index.rst @@ -0,0 +1,28 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _someipd: + +someipd +####### + +Abstract +======== + +The SOME/IP daemon. Wraps the SOME/IP protocol stack, handles Service Discovery, and routes messages between remote peers and local IPC clients. + +.. toctree:: + :maxdepth: 1 + + requirements/index diff --git a/score/someipd/docs/requirements/index.rst b/score/someipd/docs/requirements/index.rst new file mode 100644 index 000000000..7ae4968c8 --- /dev/null +++ b/score/someipd/docs/requirements/index.rst @@ -0,0 +1,20 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +############ + +.. toctree:: + + requirements diff --git a/score/someipd/docs/requirements/requirements.rst b/score/someipd/docs/requirements/requirements.rst new file mode 100644 index 000000000..4fe93612a --- /dev/null +++ b/score/someipd/docs/requirements/requirements.rst @@ -0,0 +1,36 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Component someipd Requirements +############################## + +Functional Requirements +----------------------- + +.. comp_req:: Route SOME/IP traffic between remote peers and local clients + :id: comp_req__someipd__remote_local_routing + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__someipd + + ``someipd`` shall run the SOME/IP protocol stack and route messages + between remote peers on the network (``RemoteNetworkService``) and + local IPC clients (``LocalNetworkService``) via its ``Routing`` + subsystem, translating between on-wire SOME/IP frames and the + internal IPC representation without exposing the network to local + clients. + From 921722cebaf4d0cc78b571dcc18cf3d370fd25e6 Mon Sep 17 00:00:00 2001 From: Gabriel Pinheiro Date: Fri, 28 Aug 2026 11:29:40 +0100 Subject: [PATCH 2/9] docs: wire quality-pack targets, code links and test links Add 14 comp_reqs across the 7 components (3 per component) Mark implementing sources with `// # req-Id:` and expose them via per-component `requirement_marked_sources` filegroups Wire `code_targets` in each component's docs/BUILD Annotate 3 tests with FullyVerifies/TestType/DerivationTechnique and tag cc_tests as `unit` / `component` Add //:unit_tests and //:component_tests aggregate suites Add docs/quality_pack.rst documenting the pack and baseline --- BUILD | 27 ++++ docs/index.rst | 1 + docs/quality_pack.rst | 148 ++++++++++++++++++ score/config/BUILD.bazel | 8 + score/config/docs/BUILD | 1 + .../config/docs/requirements/requirements.rst | 32 ++++ score/config/mw_someip_config.fbs | 4 + score/gateway_ipc_binding/BUILD | 11 ++ score/gateway_ipc_binding/docs/BUILD | 1 + .../docs/requirements/requirements.rst | 30 ++++ .../gateway_ipc_binding/impl/binding_base.cpp | 2 + .../impl/shared_memory_slot_manager.cpp | 1 + score/gateway_ipc_binding/test/BUILD | 1 + .../test/bidirectional_int_test.cpp | 6 + score/gatewayd/BUILD.bazel | 11 ++ score/gatewayd/docs/BUILD | 1 + .../docs/requirements/requirements.rst | 30 ++++ .../gatewayd/impl/local_service_instance.cpp | 2 + .../gatewayd/impl/remote_service_instance.cpp | 1 + score/serializer/BUILD.bazel | 12 ++ score/serializer/docs/BUILD | 1 + .../docs/requirements/requirements.rst | 30 ++++ score/serializer/null_serializer.cpp | 4 + score/serializer/null_serializer_test.cpp | 4 + score/socom/BUILD | 12 ++ score/socom/docs/BUILD | 1 + .../socom/docs/requirements/requirements.rst | 30 ++++ score/socom/impl/runtime_impl.cpp | 1 + score/socom/impl/service_identifier.cpp | 1 + score/socom/impl/string_registry.cpp | 1 + score/socom/test/stress/BUILD | 1 + score/socom/test/unit/BUILD | 1 + .../socom/test/unit/string_registry_tests.cpp | 3 + score/someip/BUILD.bazel | 11 ++ score/someip/constants.h | 3 + score/someip/docs/BUILD | 1 + .../someip/docs/requirements/requirements.rst | 29 ++++ score/someip/types.h | 2 + score/someipd/BUILD.bazel | 11 ++ score/someipd/docs/BUILD | 1 + .../docs/requirements/requirements.rst | 30 ++++ score/someipd/impl/local_network_service.cpp | 1 + score/someipd/impl/routing.cpp | 2 + 43 files changed, 511 insertions(+) create mode 100644 docs/quality_pack.rst diff --git a/BUILD b/BUILD index 4eb6e9255..d69ae738d 100644 --- a/BUILD +++ b/BUILD @@ -35,6 +35,33 @@ use_format_targets( # Documentation # ============================================================================== +# ============================================================================== +# Quality-pack aggregate test suites +# ============================================================================== +# Unit tests (tagged `unit`). A test_suite in a top-level BUILD file cannot use +# a package wildcard like `//score/...` in its `tests` attribute, so unit tests +# are aggregated by explicit label. Run with: +# bazel test //:unit_tests +test_suite( + name = "unit_tests", + tests = [ + "//score/serializer:null_serializer_test", + "//score/socom/test/unit:socom_test", + ], + visibility = ["//visibility:public"], +) + +# Component-level tests (integration / stress, tagged `component`). Run with: +# bazel test //:component_tests +test_suite( + name = "component_tests", + tests = [ + "//score/gateway_ipc_binding/test:gateway_ipc_binding_test", + "//score/socom/test/stress:socom_stress_test", + ], + visibility = ["//visibility:public"], +) + docs( bundles = [ { diff --git a/docs/index.rst b/docs/index.rst index 944be9c3c..18f722e53 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -81,6 +81,7 @@ Module / Feature Documentation requirements/index architecture/index.rst tc8_conformance/index.rst + quality_pack Component documentation diff --git a/docs/quality_pack.rst b/docs/quality_pack.rst new file mode 100644 index 000000000..68c682d35 --- /dev/null +++ b/docs/quality_pack.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 + # ******************************************************************************* + +Quality Pack Targets +#################### + +The ``score_someip_gateway`` module plugs into the Score docs-as-code +dashboards and quality gates as described in the upstream how-to: +https://eclipse-score.github.io/docs-as-code/main/how-to/dashboards_and_quality_gates.html. + +The Bazel targets below are the ones consumed by CI to produce +dashboard artefacts and to enforce traceability thresholds. + +Unit tests +========== + +- **Tag:** ``unit`` (carried by every ``cc_test`` intended as a unit + test, currently ``//score/serializer:null_serializer_test`` and + ``//score/socom/test/unit:socom_test``). +- **Aggregate target:** ``//:unit_tests``. +- **Command:** ``bazel test //:unit_tests``. +- **Results:** JUnit XML and stdout log per test target under + ``bazel-testlogs///{test.log,test.xml}``. + +Component tests +=============== + +Component tests exercise a component together with real collaborators +(SOCom runtime plus the gateway IPC binding, or the SOCom stress harness). +They cross more than one translation unit and rely on the real +``message_passing`` / shared-memory transports. + +- **Tag:** ``component``. +- **Aggregate target:** ``//:component_tests``. +- **Command:** ``bazel test //:component_tests``. +- **Included tests (existing tests reclassified, not new ones):** + + - ``//score/gateway_ipc_binding/test:gateway_ipc_binding_test`` + - ``//score/socom/test/stress:socom_stress_test`` + +- **Results:** JUnit XML and stdout log per test target under + ``bazel-testlogs///{test.log,test.xml}``. + +Code coverage +============= + +- **Config:** ``coverage.bazelrc`` (LLVM ``llvm-cov`` toolchain). +- **Command:** ``bazel coverage --config=coverage //:unit_tests //:component_tests``. +- **Results:** raw ``lcov`` data under + ``$(bazel info output_path)/_coverage/_coverage_report.dat``. Report + post-processing (HTML / Cobertura) uses the standard + ``score_tooling`` coverage flow shared with the rest of S-CORE. + +Requirements traceability (dashboards + gate) +============================================= + +Component requirements live alongside each component under +``score//docs/requirements/requirements.rst`` and use the +Score metamodel ``comp_req::`` directive. The externally-visible +feature-level requirements (``feat_req__some_ip_gateway__*``) belong to +the upstream ``eclipse-score/score`` repo (see +`Open SOME/IP `_ for +the protocol these features track). Once ``@score_platform`` / +``@score_process`` needs.json can be consumed cleanly from this repo, +they will be pulled in via the ``external_needs`` attribute of the +root ``docs()`` macro. + +Source-code and test-code links are consumed by ``score_docs_as_code``: + +- **Source-code markers** — in the C++ implementation: + + .. code-block:: cpp + + // # req-Id: comp_req__gatewayd__publish_local_instance + void LocalServiceInstance::offer() { ... } + + The leading ``// #`` is intentional; the linker regex looks for the + literal token ``# req-Id:`` and this is the neutral C++ form. The + files that carry markers are collected per component in a + ``requirement_marked_sources`` ``filegroup`` (for example + ``//score/gatewayd:requirement_marked_sources``) and passed to each + component's ``docs_bundle`` via its ``code_targets`` attribute. + +- **Test-code links** — use GoogleTest ``RecordProperty`` inside each + linked test body: + + .. code-block:: cpp + + TEST(StringRegistryTest, InsertMultipleStrings) + { + RecordProperty("FullyVerifies", "comp_req__socom__string_registry"); + RecordProperty("TestType", "requirements-based"); + RecordProperty("DerivationTechnique", "requirements-analysis"); + ... + } + + The properties land in ``bazel-testlogs/.../test.xml`` and are read by + ``score_source_code_linker`` when docs are built. All three properties + are required for the test to be counted as a link (a bare + ``FullyVerifies`` without ``TestType`` and ``DerivationTechnique`` is + captured but discarded by ``DataOfTestCase.is_valid``). + +- **Bazel targets:** + + - ``//:docs`` — HTML output plus ``_build/needs.json`` and + ``_build/metrics.json`` (traceability metrics extracted from needs). + +- **Local flow** (order matters — the docs build reads ``bazel-testlogs`` + for test links): + + .. code-block:: bash + + bazel test //:unit_tests //:component_tests + bazel run //:docs + + Current baseline (component requirements only): + + ========================= =============== + Metric Value + ========================= =============== + Requirements total 31 + Requirements with source 21/31 (67.7%) + Requirements with test 3/31 (9.7%) + Requirements fully linked 3/31 (9.7%) + ========================= =============== + + Suggested initial gate thresholds (matching the current baseline so + the gate never regresses without a follow-up ticket): + + ==================== ===== + Threshold Value + ==================== ===== + min-req-code 67 + min-req-test 9 + min-req-fully-linked 9 + min-tests-linked 1 + ==================== ===== diff --git a/score/config/BUILD.bazel b/score/config/BUILD.bazel index e1d72d2ed..e86cc8abe 100644 --- a/score/config/BUILD.bazel +++ b/score/config/BUILD.bazel @@ -22,6 +22,14 @@ exports_files( ], ) +# Files carrying `# req-Id:` markers, consumed by +# //score/config/docs:docs_bundle via its code_targets attribute. +filegroup( + name = "requirement_marked_sources", + srcs = ["mw_someip_config.fbs"], + visibility = ["//visibility:public"], +) + flatbuffer_cc_library( name = "config_flatbuffers", srcs = ["mw_someip_config.fbs"], diff --git a/score/config/docs/BUILD b/score/config/docs/BUILD index 8468d3310..2435d7904 100644 --- a/score/config/docs/BUILD +++ b/score/config/docs/BUILD @@ -17,6 +17,7 @@ load("@score_docs_as_code//:docs.bzl", "docs_bundle") # BUILD does not need to load @score_docs_as_code. docs_bundle( name = "docs_bundle", + code_targets = ["//score/config:requirement_marked_sources"], source_dir = "", visibility = ["//visibility:public"], ) diff --git a/score/config/docs/requirements/requirements.rst b/score/config/docs/requirements/requirements.rst index 89af113cd..4672e677e 100644 --- a/score/config/docs/requirements/requirements.rst +++ b/score/config/docs/requirements/requirements.rst @@ -32,3 +32,35 @@ Functional Requirements (``mw_someip_config.schema.json``) so both binary and JSON forms of the configuration can be validated against a single source of truth. +.. comp_req:: Service instance identity keyed by SOME/IP IDs + :id: comp_req__config__service_instance_ids + :reqtype: Interface + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__config + + The configuration schema shall represent every service via a 16-bit + ``service_id``, an 8-bit ``service_version_major`` and a 32-bit + ``service_version_minor`` (SOME/IP wildcard ``0xFFFFFFFF`` allowed), + and every service instance via a 16-bit ``instance_id``, so that the + on-wire identity of every configured service and instance matches + the SOME/IP header fields defined by the open protocol + specification. + +.. comp_req:: Separate local and remote service instance sets per service type + :id: comp_req__config__local_remote_split + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__config + + Each ``ServiceType`` shall carry two disjoint lists, + ``local_service_instances`` (offered from this host) and + ``remote_service_instances`` (consumed from remote hosts), so the + gateway can decide from configuration alone which instances to + publish and which to subscribe to. + diff --git a/score/config/mw_someip_config.fbs b/score/config/mw_someip_config.fbs index 3149aa594..74b97fb2b 100644 --- a/score/config/mw_someip_config.fbs +++ b/score/config/mw_someip_config.fbs @@ -1,3 +1,7 @@ +// # req-Id: comp_req__config__flatbuffer_schema +// # req-Id: comp_req__config__service_instance_ids +// # req-Id: comp_req__config__local_remote_split + namespace score.mw_someip_config; /// Top-level element of the gateway configuration diff --git a/score/gateway_ipc_binding/BUILD b/score/gateway_ipc_binding/BUILD index 107d02b98..dc1b8bd32 100644 --- a/score/gateway_ipc_binding/BUILD +++ b/score/gateway_ipc_binding/BUILD @@ -14,6 +14,17 @@ load("@rules_cc//cc:cc_library.bzl", "cc_library") load("@score_baselibs//score/language/safecpp:toolchain_features.bzl", "COMPILER_WARNING_FEATURES") +# Files carrying `// # req-Id:` markers, consumed by +# //score/gateway_ipc_binding/docs:docs_bundle via its code_targets attribute. +filegroup( + name = "requirement_marked_sources", + srcs = [ + "impl/binding_base.cpp", + "impl/shared_memory_slot_manager.cpp", + ], + visibility = ["//visibility:public"], +) + filegroup( name = "headers", srcs = glob([ diff --git a/score/gateway_ipc_binding/docs/BUILD b/score/gateway_ipc_binding/docs/BUILD index 2bf2ea578..a529568ba 100644 --- a/score/gateway_ipc_binding/docs/BUILD +++ b/score/gateway_ipc_binding/docs/BUILD @@ -17,6 +17,7 @@ load("@score_docs_as_code//:docs.bzl", "docs_bundle") # load() of @score_docs_as_code. docs_bundle( name = "docs_bundle", + code_targets = ["//score/gateway_ipc_binding:requirement_marked_sources"], source_dir = "", visibility = ["//visibility:public"], ) diff --git a/score/gateway_ipc_binding/docs/requirements/requirements.rst b/score/gateway_ipc_binding/docs/requirements/requirements.rst index eac79b514..06530e1e7 100644 --- a/score/gateway_ipc_binding/docs/requirements/requirements.rst +++ b/score/gateway_ipc_binding/docs/requirements/requirements.rst @@ -35,3 +35,33 @@ Functional Requirements the control channel, referenced by a ``Shared_memory_handle`` and released via ``Payload_consumed``. +.. comp_req:: Fixed-size shared memory slot allocation + :id: comp_req__gateway_ipc_binding__slot_alloc + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__gateway_ipc_binding + + The binding shall allocate event payloads out of a + ``SharedMemorySlotManager`` backed by a ``FixedSizeContainer`` so + that payload allocation, transmission and reclaim happen without + dynamic allocation on the hot path and without heap fragmentation + in long-running gateway processes. + +.. comp_req:: Deferred connection setup for late peers + :id: comp_req__gateway_ipc_binding__pending_conn + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__gateway_ipc_binding + + When a peer requests a service that has not yet been offered, the + binding shall queue the connect attempt in ``PendingConnects`` and + complete the connection automatically once the corresponding + ``OfferService`` is received, so client and server startup order do + not need to be coordinated externally. + diff --git a/score/gateway_ipc_binding/impl/binding_base.cpp b/score/gateway_ipc_binding/impl/binding_base.cpp index 2ad62bdcc..32be13145 100644 --- a/score/gateway_ipc_binding/impl/binding_base.cpp +++ b/score/gateway_ipc_binding/impl/binding_base.cpp @@ -11,6 +11,8 @@ * SPDX-License-Identifier: Apache-2.0 ********************************************************************************/ +// # req-Id: comp_req__gateway_ipc_binding__ctrl_chan +// # req-Id: comp_req__gateway_ipc_binding__pending_conn #include "binding_base.hpp" #include diff --git a/score/gateway_ipc_binding/impl/shared_memory_slot_manager.cpp b/score/gateway_ipc_binding/impl/shared_memory_slot_manager.cpp index 85b4e56be..f03b5ac03 100644 --- a/score/gateway_ipc_binding/impl/shared_memory_slot_manager.cpp +++ b/score/gateway_ipc_binding/impl/shared_memory_slot_manager.cpp @@ -11,6 +11,7 @@ * SPDX-License-Identifier: Apache-2.0 ********************************************************************************/ +// # req-Id: comp_req__gateway_ipc_binding__slot_alloc #include "score/gateway_ipc_binding/shared_memory_slot_manager.hpp" #include diff --git a/score/gateway_ipc_binding/test/BUILD b/score/gateway_ipc_binding/test/BUILD index 3fea9a0a1..14d5b9736 100644 --- a/score/gateway_ipc_binding/test/BUILD +++ b/score/gateway_ipc_binding/test/BUILD @@ -26,6 +26,7 @@ cc_test( "TSAN_OPTIONS": "halt_on_error=1 suppressions=$(location tsan.supp)", }, features = COMPILER_WARNING_FEATURES, + tags = ["component"], deps = [ "//score/gateway_ipc_binding", "//score/socom", diff --git a/score/gateway_ipc_binding/test/bidirectional_int_test.cpp b/score/gateway_ipc_binding/test/bidirectional_int_test.cpp index 1bce47e56..06c2646f7 100644 --- a/score/gateway_ipc_binding/test/bidirectional_int_test.cpp +++ b/score/gateway_ipc_binding/test/bidirectional_int_test.cpp @@ -42,6 +42,9 @@ using namespace std::chrono_literals; namespace score::gateway_ipc_binding { TEST_F(Gateway_ipc_binding_unconnected_integration_test, connect) { + RecordProperty("FullyVerifies", "comp_req__gateway_ipc_binding__ctrl_chan"); + RecordProperty("TestType", "requirements-based"); + RecordProperty("DerivationTechnique", "requirements-analysis"); // This test verifies that a client can connect to the server and receive a reply. // Start the server @@ -88,6 +91,9 @@ INSTANTIATE_TEST_SUITE_P(, Gateway_ipc_binding_connected_bidirectional_integrati readable_test_names); TEST_P(Gateway_ipc_binding_connected_bidirectional_integration_test, client_subscribes_to_event) { + RecordProperty("FullyVerifies", "comp_req__gateway_ipc_binding__pending_conn"); + RecordProperty("TestType", "requirements-based"); + RecordProperty("DerivationTechnique", "requirements-analysis"); std::promise event_subscription_change_promise; EXPECT_CALL(server.mock_event_subscription_change_cb, Call(_, event_id, socom::Event_state::subscribed)) diff --git a/score/gatewayd/BUILD.bazel b/score/gatewayd/BUILD.bazel index 7f571d64f..cdb50257e 100644 --- a/score/gatewayd/BUILD.bazel +++ b/score/gatewayd/BUILD.bazel @@ -26,6 +26,17 @@ exports_files( ], ) +# Files carrying `// # req-Id:` markers, consumed by +# //score/gatewayd/docs:docs_bundle via its code_targets attribute. +filegroup( + name = "requirement_marked_sources", + srcs = [ + "impl/local_service_instance.cpp", + "impl/remote_service_instance.cpp", + ], + visibility = ["//visibility:public"], +) + cc_binary( name = "gatewayd", srcs = ["main.cpp"], diff --git a/score/gatewayd/docs/BUILD b/score/gatewayd/docs/BUILD index 8468d3310..3ec7e054e 100644 --- a/score/gatewayd/docs/BUILD +++ b/score/gatewayd/docs/BUILD @@ -17,6 +17,7 @@ load("@score_docs_as_code//:docs.bzl", "docs_bundle") # BUILD does not need to load @score_docs_as_code. docs_bundle( name = "docs_bundle", + code_targets = ["//score/gatewayd:requirement_marked_sources"], source_dir = "", visibility = ["//visibility:public"], ) diff --git a/score/gatewayd/docs/requirements/requirements.rst b/score/gatewayd/docs/requirements/requirements.rst index 582172e3b..804433715 100644 --- a/score/gatewayd/docs/requirements/requirements.rst +++ b/score/gatewayd/docs/requirements/requirements.rst @@ -34,3 +34,33 @@ Functional Requirements two sides so that an application client is unaware of the transport layer. +.. comp_req:: Publish locally hosted service instances on the SOME/IP network + :id: comp_req__gatewayd__publish_local_instance + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__gatewayd + + For every ``local_service_instance`` in the configuration + ``gatewayd`` shall instantiate a ``LocalServiceInstance`` that + translates local IPC service offers and event updates into SOME/IP + Service Discovery *Offer Service* entries and SOME/IP messages on + the network side. + +.. comp_req:: Subscribe to remote SOME/IP service instances on behalf of local clients + :id: comp_req__gatewayd__consume_remote_instance + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__gatewayd + + For every ``remote_service_instance`` in the configuration + ``gatewayd`` shall instantiate a ``RemoteServiceInstance`` that + consumes SOME/IP Service Discovery *Find/Offer* exchanges and + forwards received SOME/IP messages to any local IPC clients that + subscribed to that instance via SOCom. + diff --git a/score/gatewayd/impl/local_service_instance.cpp b/score/gatewayd/impl/local_service_instance.cpp index b163e79f8..fdbfa09ae 100644 --- a/score/gatewayd/impl/local_service_instance.cpp +++ b/score/gatewayd/impl/local_service_instance.cpp @@ -11,6 +11,8 @@ * SPDX-License-Identifier: Apache-2.0 ********************************************************************************/ +// # req-Id: comp_req__gatewayd__publish_local_instance +// # req-Id: comp_req__gatewayd__local_remote_bridging #include "local_service_instance.h" #include diff --git a/score/gatewayd/impl/remote_service_instance.cpp b/score/gatewayd/impl/remote_service_instance.cpp index 2b41c86bc..f371c07c5 100644 --- a/score/gatewayd/impl/remote_service_instance.cpp +++ b/score/gatewayd/impl/remote_service_instance.cpp @@ -11,6 +11,7 @@ * SPDX-License-Identifier: Apache-2.0 ********************************************************************************/ +// # req-Id: comp_req__gatewayd__consume_remote_instance #include "remote_service_instance.h" #include diff --git a/score/serializer/BUILD.bazel b/score/serializer/BUILD.bazel index 049466f68..baa4d955d 100644 --- a/score/serializer/BUILD.bazel +++ b/score/serializer/BUILD.bazel @@ -16,6 +16,17 @@ load("@rules_cc//cc:cc_library.bzl", "cc_library") load("@rules_cc//cc:cc_shared_library.bzl", "cc_shared_library") load("@rules_cc//cc:cc_test.bzl", "cc_test") +# Files carrying `// # req-Id:` markers, consumed by +# //score/serializer/docs:docs_bundle via its code_targets attribute. +filegroup( + name = "requirement_marked_sources", + srcs = [ + "null_serializer.cpp", + "serializer.h", + ], + visibility = ["//visibility:public"], +) + # Interface between gatewayd and the serializer library. The interface is defined as a C header file and the actual implementation is provided by a shared library which is loaded at runtime by gatewayd. cc_library( name = "interface", @@ -46,6 +57,7 @@ cc_test( name = "null_serializer_test", size = "small", srcs = ["null_serializer_test.cpp"], + tags = ["unit"], deps = [ ":null_serializer_impl", ":pre_serialized_data", diff --git a/score/serializer/docs/BUILD b/score/serializer/docs/BUILD index 8468d3310..0fc4b0de2 100644 --- a/score/serializer/docs/BUILD +++ b/score/serializer/docs/BUILD @@ -17,6 +17,7 @@ load("@score_docs_as_code//:docs.bzl", "docs_bundle") # BUILD does not need to load @score_docs_as_code. docs_bundle( name = "docs_bundle", + code_targets = ["//score/serializer:requirement_marked_sources"], source_dir = "", visibility = ["//visibility:public"], ) diff --git a/score/serializer/docs/requirements/requirements.rst b/score/serializer/docs/requirements/requirements.rst index 4857099a1..3f1fa9d00 100644 --- a/score/serializer/docs/requirements/requirements.rst +++ b/score/serializer/docs/requirements/requirements.rst @@ -33,3 +33,33 @@ Functional Requirements serialization pass while still satisfying the generic ``Serializer`` interface. +.. comp_req:: C ABI-stable serializer plugin interface + :id: comp_req__serializer__c_abi_plugin + :reqtype: Interface + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__serializer + + The serializer shall expose an ``extern "C"`` interface + (``score_com_serializer_serialize`` / ``_deserialize`` / ``_get`` / + ``_init`` / ``_deinit``) so different serializer implementations + (null, IDL-generated, third-party) can be loaded as ABI-compatible + plugins without recompiling the gateway. + +.. comp_req:: Per-element serializer lookup by service type and element kind + :id: comp_req__serializer__element_lookup + :reqtype: Interface + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__serializer + + ``score_com_serializer_get`` shall return the serializer matching a + given ``service_type`` and element kind (``event``, ``field``, + ``method_call``, ``method_response``) so events, fields and + request/response method payloads can each be (de)serialized with + the right layout without additional dispatch in the caller. + diff --git a/score/serializer/null_serializer.cpp b/score/serializer/null_serializer.cpp index 3b44c308d..6e7332e29 100644 --- a/score/serializer/null_serializer.cpp +++ b/score/serializer/null_serializer.cpp @@ -14,6 +14,10 @@ /// @file /// This file provides a "serializer" which actually doesn't serialize and just copies the memory. +// # req-Id: comp_req__serializer__null_passthrough +// # req-Id: comp_req__serializer__c_abi_plugin +// # req-Id: comp_req__serializer__element_lookup + #include #include #include diff --git a/score/serializer/null_serializer_test.cpp b/score/serializer/null_serializer_test.cpp index 0c7d832d9..dbb1ef073 100644 --- a/score/serializer/null_serializer_test.cpp +++ b/score/serializer/null_serializer_test.cpp @@ -131,6 +131,10 @@ TEST_F(NullSerializer_test, init_with_empty_file_fails) { // --- score_com_serializer_get --- TEST_F(NullSerializer_test, get_event_serializer_succeeds) { + RecordProperty("FullyVerifies", + "comp_req__serializer__element_lookup, comp_req__serializer__c_abi_plugin"); + RecordProperty("TestType", "requirements-based"); + RecordProperty("DerivationTechnique", "requirements-analysis"); const score_com_serializer* serializer = nullptr; std::string service(kTestServiceTypeName); std::string element(kTestEventName); diff --git a/score/socom/BUILD b/score/socom/BUILD index 3477ea085..0425648a3 100644 --- a/score/socom/BUILD +++ b/score/socom/BUILD @@ -14,6 +14,18 @@ load("@rules_cc//cc:cc_library.bzl", "cc_library") load("@score_baselibs//score/language/safecpp:toolchain_features.bzl", "COMPILER_WARNING_FEATURES") +# Files carrying `// # req-Id:` markers, consumed by +# //score/socom/docs:docs_bundle via its code_targets attribute. +filegroup( + name = "requirement_marked_sources", + srcs = [ + "impl/runtime_impl.cpp", + "impl/service_identifier.cpp", + "impl/string_registry.cpp", + ], + visibility = ["//visibility:public"], +) + filegroup( name = "headers", srcs = glob([ diff --git a/score/socom/docs/BUILD b/score/socom/docs/BUILD index d0ae37499..3c49321c7 100644 --- a/score/socom/docs/BUILD +++ b/score/socom/docs/BUILD @@ -17,6 +17,7 @@ load("@score_docs_as_code//:docs.bzl", "docs_bundle") # load() of @score_docs_as_code. docs_bundle( name = "docs_bundle", + code_targets = ["//score/socom:requirement_marked_sources"], source_dir = "", visibility = ["//visibility:public"], ) diff --git a/score/socom/docs/requirements/requirements.rst b/score/socom/docs/requirements/requirements.rst index ca054f8f7..835200ab6 100644 --- a/score/socom/docs/requirements/requirements.rst +++ b/score/socom/docs/requirements/requirements.rst @@ -34,3 +34,33 @@ Functional Requirements future backend) without exposing the transport details to the application. +.. comp_req:: Stable service and method identity across processes + :id: comp_req__socom__service_identity + :reqtype: Interface + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__socom + + SOCom shall provide value types (``ServiceIdentifier``, + ``Method``, ``ServiceInterfaceDefinition``) that identify a + service and its methods/events in a way that is stable across + process boundaries and independent of local pointer values, so + that the same identity round-trips faithfully through the IPC + binding and the SOME/IP wire. + +.. comp_req:: String interning for repeated protocol identifiers + :id: comp_req__socom__string_registry + :reqtype: Non-Functional + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__socom + + SOCom shall provide a ``StringRegistry`` that interns repeated + protocol strings (service type names, event/method names) so that + the runtime and transport layer can refer to them by a small + integer id instead of resending the full string on every message. + diff --git a/score/socom/impl/runtime_impl.cpp b/score/socom/impl/runtime_impl.cpp index 29b3b1427..d171ef7d8 100644 --- a/score/socom/impl/runtime_impl.cpp +++ b/score/socom/impl/runtime_impl.cpp @@ -11,6 +11,7 @@ * SPDX-License-Identifier: Apache-2.0 ********************************************************************************/ +// # req-Id: comp_req__socom__service_runtime #include "runtime_impl.hpp" #include diff --git a/score/socom/impl/service_identifier.cpp b/score/socom/impl/service_identifier.cpp index d84eb383e..3c65cffc9 100644 --- a/score/socom/impl/service_identifier.cpp +++ b/score/socom/impl/service_identifier.cpp @@ -11,6 +11,7 @@ * SPDX-License-Identifier: Apache-2.0 ********************************************************************************/ +// # req-Id: comp_req__socom__service_identity #include "service_identifier.hpp" #include diff --git a/score/socom/impl/string_registry.cpp b/score/socom/impl/string_registry.cpp index 245e06974..7f4a6bafd 100644 --- a/score/socom/impl/string_registry.cpp +++ b/score/socom/impl/string_registry.cpp @@ -11,6 +11,7 @@ * SPDX-License-Identifier: Apache-2.0 ********************************************************************************/ +// # req-Id: comp_req__socom__string_registry #include "score/socom/string_registry.hpp" #include diff --git a/score/socom/test/stress/BUILD b/score/socom/test/stress/BUILD index 846eea975..c1c46dc40 100644 --- a/score/socom/test/stress/BUILD +++ b/score/socom/test/stress/BUILD @@ -21,6 +21,7 @@ cc_test( env = { "TSAN_OPTIONS": "suppressions=$(location tsan.supp)", }, + tags = ["component"], deps = [ "//score/socom/test/framework:socom_test_framework", "@googletest//:gtest", diff --git a/score/socom/test/unit/BUILD b/score/socom/test/unit/BUILD index 9c6dc1421..3dc39d6c0 100644 --- a/score/socom/test/unit/BUILD +++ b/score/socom/test/unit/BUILD @@ -17,6 +17,7 @@ cc_test( name = "socom_test", size = "small", srcs = glob(include = ["*.cpp"]), + tags = ["unit"], deps = [ "//score/socom:mock", "//score/socom/test/framework:socom_test_framework", diff --git a/score/socom/test/unit/string_registry_tests.cpp b/score/socom/test/unit/string_registry_tests.cpp index ebc590a02..ccf04fed7 100644 --- a/score/socom/test/unit/string_registry_tests.cpp +++ b/score/socom/test/unit/string_registry_tests.cpp @@ -21,6 +21,9 @@ namespace score::socom { TEST(StringRegistryTest, InsertMultipleStrings) { + RecordProperty("FullyVerifies", "comp_req__socom__string_registry"); + RecordProperty("TestType", "requirements-based"); + RecordProperty("DerivationTechnique", "requirements-analysis"); String_registry registry; /// Verify the existence of the type cara::core::util::String_registry interface. diff --git a/score/someip/BUILD.bazel b/score/someip/BUILD.bazel index 1851ae6e5..e9d982a34 100644 --- a/score/someip/BUILD.bazel +++ b/score/someip/BUILD.bazel @@ -17,6 +17,17 @@ Common types and constants shared across the SOME/IP gateway components. load("@rules_cc//cc:cc_library.bzl", "cc_library") +# Files carrying `// # req-Id:` markers, consumed by +# //score/someip/docs:docs_bundle via its code_targets attribute. +filegroup( + name = "requirement_marked_sources", + srcs = [ + "constants.h", + "types.h", + ], + visibility = ["//visibility:public"], +) + cc_library( name = "someip", hdrs = [ diff --git a/score/someip/constants.h b/score/someip/constants.h index 6d29be930..d7b4887cc 100644 --- a/score/someip/constants.h +++ b/score/someip/constants.h @@ -16,6 +16,9 @@ #include "score/someip/types.h" +// # req-Id: comp_req__someip__protocol_types +// # req-Id: comp_req__someip__protocol_limits + namespace score::someip { // ============================================================================= diff --git a/score/someip/docs/BUILD b/score/someip/docs/BUILD index 8468d3310..1110f941f 100644 --- a/score/someip/docs/BUILD +++ b/score/someip/docs/BUILD @@ -17,6 +17,7 @@ load("@score_docs_as_code//:docs.bzl", "docs_bundle") # BUILD does not need to load @score_docs_as_code. docs_bundle( name = "docs_bundle", + code_targets = ["//score/someip:requirement_marked_sources"], source_dir = "", visibility = ["//visibility:public"], ) diff --git a/score/someip/docs/requirements/requirements.rst b/score/someip/docs/requirements/requirements.rst index 5fffb43ae..f1a8db0c8 100644 --- a/score/someip/docs/requirements/requirements.rst +++ b/score/someip/docs/requirements/requirements.rst @@ -34,3 +34,32 @@ Functional Requirements ``gatewayd``) share a single canonical definition of the on-wire protocol elements. +.. comp_req:: 16-bit SOME/IP identifier types + :id: comp_req__someip__id_widths + :reqtype: Interface + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__someip + + ``types.h`` shall define ``ServiceId``, ``InstanceId``, ``EventId`` + and ``EventGroupId`` as ``std::uint16_t`` so all in-process + handling of SOME/IP identifiers matches the 16-bit widths mandated + by the SOME/IP header layout in the Open SOME/IP specification. + +.. comp_req:: Wildcard instance id and maximum message size + :id: comp_req__someip__protocol_limits + :reqtype: Interface + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__someip + + ``constants.h`` shall expose the wildcard instance id + (``kAnyInstance = 0xFFFF``), the SOME/IP header size + (``kSomeipFullHeaderSize = 16``) and the per-message size cap + (``kMaxMessageSize = 1500``) chosen to keep single SOME/IP messages + within a standard Ethernet MTU and avoid IP fragmentation. + diff --git a/score/someip/types.h b/score/someip/types.h index bda10c165..3f0eaf1f8 100644 --- a/score/someip/types.h +++ b/score/someip/types.h @@ -17,6 +17,8 @@ #include #include +// # req-Id: comp_req__someip__id_widths + namespace score::someip { using ServiceId = std::uint16_t; diff --git a/score/someipd/BUILD.bazel b/score/someipd/BUILD.bazel index 56e9ca24d..264d53075 100644 --- a/score/someipd/BUILD.bazel +++ b/score/someipd/BUILD.bazel @@ -19,6 +19,17 @@ load("@bazel_skylib//rules:native_binary.bzl", "native_binary") load("@rules_cc//cc:cc_binary.bzl", "cc_binary") load("@rules_cc//cc:cc_library.bzl", "cc_library") +# Files carrying `// # req-Id:` markers, consumed by +# //score/someipd/docs:docs_bundle via its code_targets attribute. +filegroup( + name = "requirement_marked_sources", + srcs = [ + "impl/local_network_service.cpp", + "impl/routing.cpp", + ], + visibility = ["//visibility:public"], +) + # ============================================================================ # Main Binary # ============================================================================ diff --git a/score/someipd/docs/BUILD b/score/someipd/docs/BUILD index 8468d3310..c7b8057e8 100644 --- a/score/someipd/docs/BUILD +++ b/score/someipd/docs/BUILD @@ -17,6 +17,7 @@ load("@score_docs_as_code//:docs.bzl", "docs_bundle") # BUILD does not need to load @score_docs_as_code. docs_bundle( name = "docs_bundle", + code_targets = ["//score/someipd:requirement_marked_sources"], source_dir = "", visibility = ["//visibility:public"], ) diff --git a/score/someipd/docs/requirements/requirements.rst b/score/someipd/docs/requirements/requirements.rst index 4fe93612a..492568488 100644 --- a/score/someipd/docs/requirements/requirements.rst +++ b/score/someipd/docs/requirements/requirements.rst @@ -18,6 +18,22 @@ Component someipd Requirements Functional Requirements ----------------------- +.. comp_req:: SOME/IP Service Discovery handling + :id: comp_req__someipd__sd_protocol + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__someipd + + ``someipd`` shall implement the SOME/IP Service Discovery (SD) + protocol entries (``FindService``, ``OfferService``, + ``StopOfferService``, ``Subscribe``, ``StopSubscribe``, + ``SubscribeAck``, ``SubscribeNack``) needed by the Open SOME/IP-SD + specification, so peers can discover and subscribe to SOME/IP + services offered by this host. + .. comp_req:: Route SOME/IP traffic between remote peers and local clients :id: comp_req__someipd__remote_local_routing :reqtype: Functional @@ -34,3 +50,17 @@ Functional Requirements internal IPC representation without exposing the network to local clients. +.. comp_req:: Local-only network service for gateway-hosted instances + :id: comp_req__someipd__local_network_service + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :version: 1 + :satisfied_by: comp__someipd + + The ``LocalNetworkService`` role shall handle SOME/IP messages + whose target instance is locally hosted by the gateway, so that + requests originating from remote peers reach the correct local + application without traversing an additional network hop. + diff --git a/score/someipd/impl/local_network_service.cpp b/score/someipd/impl/local_network_service.cpp index 335345795..5e211a3d3 100644 --- a/score/someipd/impl/local_network_service.cpp +++ b/score/someipd/impl/local_network_service.cpp @@ -11,6 +11,7 @@ * SPDX-License-Identifier: Apache-2.0 ********************************************************************************/ +// # req-Id: comp_req__someipd__local_network_service #include "local_network_service.h" #include diff --git a/score/someipd/impl/routing.cpp b/score/someipd/impl/routing.cpp index 1a15fe77f..dde174438 100644 --- a/score/someipd/impl/routing.cpp +++ b/score/someipd/impl/routing.cpp @@ -11,6 +11,8 @@ * SPDX-License-Identifier: Apache-2.0 ********************************************************************************/ +// # req-Id: comp_req__someipd__remote_local_routing +// # req-Id: comp_req__someipd__sd_protocol #include "routing.h" #include From 716c73459f31b55e83a42316d0b0e5316b4b850e Mon Sep 17 00:00:00 2001 From: Gabriel Pinheiro Date: Tue, 1 Sep 2026 15:50:40 +0100 Subject: [PATCH 3/9] docs: Simplify documentation and point to docs-as-code --- docs/quality_pack.rst | 95 ++++++++++++++++--------------------------- 1 file changed, 34 insertions(+), 61 deletions(-) diff --git a/docs/quality_pack.rst b/docs/quality_pack.rst index 68c682d35..cc4a1fef7 100644 --- a/docs/quality_pack.rst +++ b/docs/quality_pack.rst @@ -76,73 +76,46 @@ the protocol these features track). Once ``@score_platform`` / they will be pulled in via the ``external_needs`` attribute of the root ``docs()`` macro. -Source-code and test-code links are consumed by ``score_docs_as_code``: - -- **Source-code markers** — in the C++ implementation: - - .. code-block:: cpp +Source-code and test-code links are consumed by ``score_docs_as_code``. +See the upstream how-to for the marker syntax, the required GoogleTest +``RecordProperty`` fields, and the validation rules that decide whether a +link is counted: +https://eclipse-score.github.io/docs-as-code/main/how-to/dashboards_and_quality_gates.html. - // # req-Id: comp_req__gatewayd__publish_local_instance - void LocalServiceInstance::offer() { ... } +Repo-local wiring: - The leading ``// #`` is intentional; the linker regex looks for the - literal token ``# req-Id:`` and this is the neutral C++ form. The - files that carry markers are collected per component in a +- **Source-code markers** live in the C++ implementation files. Per + component, the marked files are collected into a ``requirement_marked_sources`` ``filegroup`` (for example - ``//score/gatewayd:requirement_marked_sources``) and passed to each - component's ``docs_bundle`` via its ``code_targets`` attribute. - -- **Test-code links** — use GoogleTest ``RecordProperty`` inside each - linked test body: - - .. code-block:: cpp - - TEST(StringRegistryTest, InsertMultipleStrings) - { - RecordProperty("FullyVerifies", "comp_req__socom__string_registry"); - RecordProperty("TestType", "requirements-based"); - RecordProperty("DerivationTechnique", "requirements-analysis"); - ... - } - - The properties land in ``bazel-testlogs/.../test.xml`` and are read by - ``score_source_code_linker`` when docs are built. All three properties - are required for the test to be counted as a link (a bare - ``FullyVerifies`` without ``TestType`` and ``DerivationTechnique`` is - captured but discarded by ``DataOfTestCase.is_valid``). - -- **Bazel targets:** - - - ``//:docs`` — HTML output plus ``_build/needs.json`` and - ``_build/metrics.json`` (traceability metrics extracted from needs). - -- **Local flow** (order matters — the docs build reads ``bazel-testlogs`` - for test links): + ``//score/gatewayd:requirement_marked_sources``) and passed to that + component's ``docs_bundle`` via ``code_targets``. Grep the tree for + ``# req-Id:`` to see current examples. +- **Test-code links** use ``RecordProperty`` inside the test body. Grep + for ``FullyVerifies`` to see current examples (for instance + ``//score/socom/test/unit:socom_test``). +- **Bazel target:** ``//:docs`` — HTML output plus ``_build/needs.json`` + and ``_build/metrics.json`` (traceability metrics extracted from needs). +- **Local flow** — order matters, the docs build reads + ``bazel-testlogs`` for test links: .. code-block:: bash bazel test //:unit_tests //:component_tests bazel run //:docs - Current baseline (component requirements only): - - ========================= =============== - Metric Value - ========================= =============== - Requirements total 31 - Requirements with source 21/31 (67.7%) - Requirements with test 3/31 (9.7%) - Requirements fully linked 3/31 (9.7%) - ========================= =============== - - Suggested initial gate thresholds (matching the current baseline so - the gate never regresses without a follow-up ticket): - - ==================== ===== - Threshold Value - ==================== ===== - min-req-code 67 - min-req-test 9 - min-req-fully-linked 9 - min-tests-linked 1 - ==================== ===== +Live coverage numbers are posted as a sticky comment on every pull +request by ``.github/workflows/quality_pack_comment.yml`` (rendered by +``tools/quality_pack/render_pr_comment.py`` from ``_build/metrics.json``); +see the workflow's uploaded ``quality-pack-metrics`` artifact for the +raw JSON. The initial gate thresholds — matching the baseline at +introduction so the gate never regresses without a follow-up ticket — +are: + + ==================== ===== =============================== + Threshold Value Meaning + ==================== ===== =============================== + min-req-code 67 ``with_code_link_pct`` ≥ 67 + min-req-test 9 ``with_test_link_pct`` ≥ 9 + min-req-fully-linked 9 ``fully_linked_pct`` ≥ 9 + min-tests-linked 1 ≥ 1 test carrying ``FullyVerifies`` + ==================== ===== =============================== From 5f4abbfacafbae4f067f9def3fa97f202d1fe5fc Mon Sep 17 00:00:00 2001 From: Gabriel Pinheiro Date: Thu, 3 Sep 2026 16:44:35 +0100 Subject: [PATCH 4/9] ci: add workflow that comments traceability gate on PRs --- .github/workflows/ci.yml | 6 ++ .github/workflows/quality_pack_comment.yml | 104 +++++++++++++++++++++ 2 files changed, 110 insertions(+) create mode 100644 .github/workflows/quality_pack_comment.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7d9489b32..b8ebc8479 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -38,6 +38,12 @@ jobs: docs: secrets: inherit uses: ./.github/workflows/docs.yml + quality_pack_comment: + secrets: inherit + permissions: + contents: read + pull-requests: write + uses: ./.github/workflows/quality_pack_comment.yml # check if PR can be enqueued to the merge queue or merged to main # individual jobs are skipped in their respective workflow files depending on the event type, # so we can just check the outcomes of all jobs here without checking the event type again. diff --git a/.github/workflows/quality_pack_comment.yml b/.github/workflows/quality_pack_comment.yml new file mode 100644 index 000000000..556515958 --- /dev/null +++ b/.github/workflows/quality_pack_comment.yml @@ -0,0 +1,104 @@ +# ******************************************************************************* +# 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 +# ******************************************************************************* + +# Builds the docs, runs the upstream //:traceability_gate against the resulting +# _build/metrics.json, and posts (or edits) a sticky PR comment with the gate +# output and pass/fail status. +# +# The comment step is best-effort: PRs from forks get a read-only GITHUB_TOKEN +# and the sticky-comment action will fail with 403 — marked continue-on-error +# so those PRs still surface the numbers via the job log and artifact. + +name: Quality pack coverage comment + +on: + workflow_call: + +jobs: + quality-pack-comment: + runs-on: ubuntu-24.04 + steps: + - uses: eclipse-score/more-disk-space@v1 + - name: Checkout repository + uses: actions/checkout@v7 + - name: Create Bazel output base directory + run: | + sudo mkdir -p /mnt/.bazel + sudo chown -R $USER:$USER /mnt/.bazel + - name: Create config indicator file + run: echo "host" > .bazel_config + - name: Setup Bazel + uses: eclipse-score/cicd-actions/setup-bazel-cache@212bbf86267e9381da9d2daf962d12f6feafbc90 # v0.0.2 + with: + unique-cache-name: ${{ github.job }} + - name: Allow linux-sandbox + uses: eclipse-score/cicd-actions/unblock-user-namespace-for-linux-sandbox@212bbf86267e9381da9d2daf962d12f6feafbc90 # v0.0.2 + - name: Build unit + component tests (needed for test links) + run: bazel test //:unit_tests //:component_tests + - name: Build docs + run: bazel run //:docs + # Thresholds are set at introduction to match the then-baseline so the gate + # never regresses without a follow-up ticket. Raise them as coverage grows. + # (--min-tests-linked is intentionally omitted — the current baseline is + # well below 1% and picking a floor now would flap the gate.) + - name: Run traceability gate + id: gate + continue-on-error: true + run: | + mkdir -p .llm_tmp + # --need-type=comp_req scopes the gate to component requirements; + # feat_req / stkh_req live upstream in eclipse-score/score and would + # otherwise pull the numbers to zero and flap the gate. + bazel run //:traceability_gate -- \ + --metrics-json "$PWD/_build/metrics.json" \ + --need-type=comp_req \ + --min-req-code=67 \ + --min-req-test=9 \ + --min-req-fully-linked=9 \ + > .llm_tmp/gate.txt + - name: Render sticky comment body + run: | + if [ "${{ steps.gate.outcome }}" = "success" ]; then + status="**PASS**" + else + status="**FAIL**" + fi + { + echo '' + echo "### Quality pack traceability — gate: $status" + echo + echo '```text' + cat .llm_tmp/gate.txt + echo '```' + echo + echo "Produced by \`//:traceability_gate\` against \`_build/metrics.json\`." + } > .llm_tmp/comment.md + cat .llm_tmp/comment.md + - name: Upload metrics + gate output + if: always() + uses: actions/upload-artifact@v7 + with: + name: quality-pack-metrics + path: | + _build/metrics.json + .llm_tmp/gate.txt + .llm_tmp/comment.md + if-no-files-found: warn + retention-days: 14 + - name: Post sticky PR comment + if: github.event_name == 'pull_request' + continue-on-error: true + uses: marocchino/sticky-pull-request-comment@52423e01640425a022ef5fd42c6fb5f633a02728 # v2.9.1 + with: + header: quality-pack-coverage + path: .llm_tmp/comment.md From 85906710d9aa58dfbb9cd7e7295154f8cd2737dc Mon Sep 17 00:00:00 2001 From: Gabriel Pinheiro Date: Thu, 3 Sep 2026 16:48:10 +0100 Subject: [PATCH 5/9] docs: move quality pack instructions from docs/ to README --- README.md | 28 ++++++++++ docs/quality_pack.rst | 121 ------------------------------------------ 2 files changed, 28 insertions(+), 121 deletions(-) delete mode 100644 docs/quality_pack.rst diff --git a/README.md b/README.md index e78c94bf7..7e283fd8a 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,34 @@ bazel run @score_tooling//coverage:generate_coverage_html The HTML report is stored at `coverage_linux/index.html`. You can open it in a web browser to view the coverage results. +## Quality pack + +Requirements traceability is produced by the documentation build. Run the tests +first: the docs build reads `bazel-testlogs` to link each requirement to the +tests that verify it. + +```sh +bazel test //:unit_tests //:component_tests +bazel run //:docs +``` + +This generates: + +- `_build/index.html` — documentation, showing the source-code and test + links on each requirement +- `_build/needs.json` — the requirements model +- `_build/metrics.json` — traceability metrics + +To print the traceability summary on the command line: + +```sh +bazel run //:traceability_gate -- --metrics-json "$PWD/_build/metrics.json" +``` + +CI runs the same gate on every pull request with thresholds attached, and +posts the summary as a sticky comment — see +`.github/workflows/quality_pack_comment.yml`. + ### Start the daemons Start the daemons in this order: diff --git a/docs/quality_pack.rst b/docs/quality_pack.rst deleted file mode 100644 index cc4a1fef7..000000000 --- a/docs/quality_pack.rst +++ /dev/null @@ -1,121 +0,0 @@ -.. - # ******************************************************************************* - # 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 - # ******************************************************************************* - -Quality Pack Targets -#################### - -The ``score_someip_gateway`` module plugs into the Score docs-as-code -dashboards and quality gates as described in the upstream how-to: -https://eclipse-score.github.io/docs-as-code/main/how-to/dashboards_and_quality_gates.html. - -The Bazel targets below are the ones consumed by CI to produce -dashboard artefacts and to enforce traceability thresholds. - -Unit tests -========== - -- **Tag:** ``unit`` (carried by every ``cc_test`` intended as a unit - test, currently ``//score/serializer:null_serializer_test`` and - ``//score/socom/test/unit:socom_test``). -- **Aggregate target:** ``//:unit_tests``. -- **Command:** ``bazel test //:unit_tests``. -- **Results:** JUnit XML and stdout log per test target under - ``bazel-testlogs///{test.log,test.xml}``. - -Component tests -=============== - -Component tests exercise a component together with real collaborators -(SOCom runtime plus the gateway IPC binding, or the SOCom stress harness). -They cross more than one translation unit and rely on the real -``message_passing`` / shared-memory transports. - -- **Tag:** ``component``. -- **Aggregate target:** ``//:component_tests``. -- **Command:** ``bazel test //:component_tests``. -- **Included tests (existing tests reclassified, not new ones):** - - - ``//score/gateway_ipc_binding/test:gateway_ipc_binding_test`` - - ``//score/socom/test/stress:socom_stress_test`` - -- **Results:** JUnit XML and stdout log per test target under - ``bazel-testlogs///{test.log,test.xml}``. - -Code coverage -============= - -- **Config:** ``coverage.bazelrc`` (LLVM ``llvm-cov`` toolchain). -- **Command:** ``bazel coverage --config=coverage //:unit_tests //:component_tests``. -- **Results:** raw ``lcov`` data under - ``$(bazel info output_path)/_coverage/_coverage_report.dat``. Report - post-processing (HTML / Cobertura) uses the standard - ``score_tooling`` coverage flow shared with the rest of S-CORE. - -Requirements traceability (dashboards + gate) -============================================= - -Component requirements live alongside each component under -``score//docs/requirements/requirements.rst`` and use the -Score metamodel ``comp_req::`` directive. The externally-visible -feature-level requirements (``feat_req__some_ip_gateway__*``) belong to -the upstream ``eclipse-score/score`` repo (see -`Open SOME/IP `_ for -the protocol these features track). Once ``@score_platform`` / -``@score_process`` needs.json can be consumed cleanly from this repo, -they will be pulled in via the ``external_needs`` attribute of the -root ``docs()`` macro. - -Source-code and test-code links are consumed by ``score_docs_as_code``. -See the upstream how-to for the marker syntax, the required GoogleTest -``RecordProperty`` fields, and the validation rules that decide whether a -link is counted: -https://eclipse-score.github.io/docs-as-code/main/how-to/dashboards_and_quality_gates.html. - -Repo-local wiring: - -- **Source-code markers** live in the C++ implementation files. Per - component, the marked files are collected into a - ``requirement_marked_sources`` ``filegroup`` (for example - ``//score/gatewayd:requirement_marked_sources``) and passed to that - component's ``docs_bundle`` via ``code_targets``. Grep the tree for - ``# req-Id:`` to see current examples. -- **Test-code links** use ``RecordProperty`` inside the test body. Grep - for ``FullyVerifies`` to see current examples (for instance - ``//score/socom/test/unit:socom_test``). -- **Bazel target:** ``//:docs`` — HTML output plus ``_build/needs.json`` - and ``_build/metrics.json`` (traceability metrics extracted from needs). -- **Local flow** — order matters, the docs build reads - ``bazel-testlogs`` for test links: - - .. code-block:: bash - - bazel test //:unit_tests //:component_tests - bazel run //:docs - -Live coverage numbers are posted as a sticky comment on every pull -request by ``.github/workflows/quality_pack_comment.yml`` (rendered by -``tools/quality_pack/render_pr_comment.py`` from ``_build/metrics.json``); -see the workflow's uploaded ``quality-pack-metrics`` artifact for the -raw JSON. The initial gate thresholds — matching the baseline at -introduction so the gate never regresses without a follow-up ticket — -are: - - ==================== ===== =============================== - Threshold Value Meaning - ==================== ===== =============================== - min-req-code 67 ``with_code_link_pct`` ≥ 67 - min-req-test 9 ``with_test_link_pct`` ≥ 9 - min-req-fully-linked 9 ``fully_linked_pct`` ≥ 9 - min-tests-linked 1 ≥ 1 test carrying ``FullyVerifies`` - ==================== ===== =============================== From 53850b1a44a8a7eb7f83daee7b4016b6a9b87793 Mon Sep 17 00:00:00 2001 From: Gabriel Pinheiro Date: Fri, 4 Sep 2026 13:35:39 +0100 Subject: [PATCH 6/9] docs: remove implementation-derived comp_req entries --- .github/workflows/quality_pack_comment.yml | 10 +-- docs/index.rst | 1 - score/config/BUILD.bazel | 8 --- score/config/docs/BUILD | 1 - score/config/docs/index.rst | 5 -- score/config/docs/requirements/index.rst | 20 ------ .../config/docs/requirements/requirements.rst | 66 ------------------ score/config/mw_someip_config.fbs | 4 -- score/gateway_ipc_binding/BUILD | 11 --- score/gateway_ipc_binding/docs/BUILD | 1 - score/gateway_ipc_binding/docs/index.rst | 1 - .../docs/requirements/index.rst | 20 ------ .../docs/requirements/requirements.rst | 67 ------------------- .../gateway_ipc_binding/impl/binding_base.cpp | 2 - .../impl/shared_memory_slot_manager.cpp | 1 - .../test/bidirectional_int_test.cpp | 6 -- score/gatewayd/BUILD.bazel | 11 --- score/gatewayd/docs/BUILD | 1 - score/gatewayd/docs/index.rst | 5 -- score/gatewayd/docs/requirements/index.rst | 20 ------ .../docs/requirements/requirements.rst | 66 ------------------ .../gatewayd/impl/local_service_instance.cpp | 2 - .../gatewayd/impl/remote_service_instance.cpp | 1 - score/serializer/BUILD.bazel | 11 --- score/serializer/docs/BUILD | 1 - score/serializer/docs/index.rst | 5 -- score/serializer/docs/requirements/index.rst | 20 ------ .../docs/requirements/requirements.rst | 65 ------------------ score/serializer/null_serializer.cpp | 4 -- score/serializer/null_serializer_test.cpp | 4 -- score/socom/BUILD | 12 ---- score/socom/docs/BUILD | 1 - score/socom/docs/index.rst | 1 - score/socom/docs/requirements/index.rst | 20 ------ .../socom/docs/requirements/requirements.rst | 66 ------------------ score/socom/impl/runtime_impl.cpp | 1 - score/socom/impl/service_identifier.cpp | 1 - score/socom/impl/string_registry.cpp | 1 - .../socom/test/unit/string_registry_tests.cpp | 3 - score/someip/BUILD.bazel | 11 --- score/someip/constants.h | 3 - score/someip/docs/BUILD | 1 - score/someip/docs/index.rst | 5 -- score/someip/docs/requirements/index.rst | 20 ------ .../someip/docs/requirements/requirements.rst | 65 ------------------ score/someip/types.h | 2 - score/someipd/BUILD.bazel | 11 --- score/someipd/docs/BUILD | 1 - score/someipd/docs/index.rst | 5 -- score/someipd/docs/requirements/index.rst | 20 ------ .../docs/requirements/requirements.rst | 66 ------------------ score/someipd/impl/local_network_service.cpp | 1 - score/someipd/impl/routing.cpp | 2 - 53 files changed, 3 insertions(+), 756 deletions(-) delete mode 100644 score/config/docs/requirements/index.rst delete mode 100644 score/config/docs/requirements/requirements.rst delete mode 100644 score/gateway_ipc_binding/docs/requirements/index.rst delete mode 100644 score/gateway_ipc_binding/docs/requirements/requirements.rst delete mode 100644 score/gatewayd/docs/requirements/index.rst delete mode 100644 score/gatewayd/docs/requirements/requirements.rst delete mode 100644 score/serializer/docs/requirements/index.rst delete mode 100644 score/serializer/docs/requirements/requirements.rst delete mode 100644 score/socom/docs/requirements/index.rst delete mode 100644 score/socom/docs/requirements/requirements.rst delete mode 100644 score/someip/docs/requirements/index.rst delete mode 100644 score/someip/docs/requirements/requirements.rst delete mode 100644 score/someipd/docs/requirements/index.rst delete mode 100644 score/someipd/docs/requirements/requirements.rst diff --git a/.github/workflows/quality_pack_comment.yml b/.github/workflows/quality_pack_comment.yml index 556515958..83fc9b149 100644 --- a/.github/workflows/quality_pack_comment.yml +++ b/.github/workflows/quality_pack_comment.yml @@ -47,10 +47,9 @@ jobs: run: bazel test //:unit_tests //:component_tests - name: Build docs run: bazel run //:docs - # Thresholds are set at introduction to match the then-baseline so the gate - # never regresses without a follow-up ticket. Raise them as coverage grows. - # (--min-tests-linked is intentionally omitted — the current baseline is - # well below 1% and picking a floor now would flap the gate.) + # Thresholds default to 0 while comp_req coverage is being (re-)built up + # against the SOME/IP protocol spec. Raise the --min-* flags as + # links land, so the gate never regresses without a follow-up ticket. - name: Run traceability gate id: gate continue-on-error: true @@ -62,9 +61,6 @@ jobs: bazel run //:traceability_gate -- \ --metrics-json "$PWD/_build/metrics.json" \ --need-type=comp_req \ - --min-req-code=67 \ - --min-req-test=9 \ - --min-req-fully-linked=9 \ > .llm_tmp/gate.txt - name: Render sticky comment body run: | diff --git a/docs/index.rst b/docs/index.rst index 18f722e53..944be9c3c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -81,7 +81,6 @@ Module / Feature Documentation requirements/index architecture/index.rst tc8_conformance/index.rst - quality_pack Component documentation diff --git a/score/config/BUILD.bazel b/score/config/BUILD.bazel index e86cc8abe..e1d72d2ed 100644 --- a/score/config/BUILD.bazel +++ b/score/config/BUILD.bazel @@ -22,14 +22,6 @@ exports_files( ], ) -# Files carrying `# req-Id:` markers, consumed by -# //score/config/docs:docs_bundle via its code_targets attribute. -filegroup( - name = "requirement_marked_sources", - srcs = ["mw_someip_config.fbs"], - visibility = ["//visibility:public"], -) - flatbuffer_cc_library( name = "config_flatbuffers", srcs = ["mw_someip_config.fbs"], diff --git a/score/config/docs/BUILD b/score/config/docs/BUILD index 2435d7904..8468d3310 100644 --- a/score/config/docs/BUILD +++ b/score/config/docs/BUILD @@ -17,7 +17,6 @@ load("@score_docs_as_code//:docs.bzl", "docs_bundle") # BUILD does not need to load @score_docs_as_code. docs_bundle( name = "docs_bundle", - code_targets = ["//score/config:requirement_marked_sources"], source_dir = "", visibility = ["//visibility:public"], ) diff --git a/score/config/docs/index.rst b/score/config/docs/index.rst index 8b99a507e..d850a2f57 100644 --- a/score/config/docs/index.rst +++ b/score/config/docs/index.rst @@ -29,8 +29,3 @@ Abstract ======== Provides the FlatBuffers schema (mw_someip_config.fbs) and JSON schema used to define and validate gateway configuration. - -.. toctree:: - :maxdepth: 1 - - requirements/index diff --git a/score/config/docs/requirements/index.rst b/score/config/docs/requirements/index.rst deleted file mode 100644 index 7ae4968c8..000000000 --- a/score/config/docs/requirements/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. - # ******************************************************************************* - # 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 - # ******************************************************************************* - -Requirements -############ - -.. toctree:: - - requirements diff --git a/score/config/docs/requirements/requirements.rst b/score/config/docs/requirements/requirements.rst deleted file mode 100644 index 4672e677e..000000000 --- a/score/config/docs/requirements/requirements.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. - # ******************************************************************************* - # 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 - # ******************************************************************************* - -Component Config Requirements -############################# - -Functional Requirements ------------------------ - -.. comp_req:: FlatBuffers gateway configuration schema - :id: comp_req__config__flatbuffer_schema - :reqtype: Interface - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__config - - The gateway configuration shall be defined as a FlatBuffers schema - (``mw_someip_config.fbs``) together with a JSON schema - (``mw_someip_config.schema.json``) so both binary and JSON forms of - the configuration can be validated against a single source of truth. - -.. comp_req:: Service instance identity keyed by SOME/IP IDs - :id: comp_req__config__service_instance_ids - :reqtype: Interface - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__config - - The configuration schema shall represent every service via a 16-bit - ``service_id``, an 8-bit ``service_version_major`` and a 32-bit - ``service_version_minor`` (SOME/IP wildcard ``0xFFFFFFFF`` allowed), - and every service instance via a 16-bit ``instance_id``, so that the - on-wire identity of every configured service and instance matches - the SOME/IP header fields defined by the open protocol - specification. - -.. comp_req:: Separate local and remote service instance sets per service type - :id: comp_req__config__local_remote_split - :reqtype: Functional - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__config - - Each ``ServiceType`` shall carry two disjoint lists, - ``local_service_instances`` (offered from this host) and - ``remote_service_instances`` (consumed from remote hosts), so the - gateway can decide from configuration alone which instances to - publish and which to subscribe to. - diff --git a/score/config/mw_someip_config.fbs b/score/config/mw_someip_config.fbs index 74b97fb2b..3149aa594 100644 --- a/score/config/mw_someip_config.fbs +++ b/score/config/mw_someip_config.fbs @@ -1,7 +1,3 @@ -// # req-Id: comp_req__config__flatbuffer_schema -// # req-Id: comp_req__config__service_instance_ids -// # req-Id: comp_req__config__local_remote_split - namespace score.mw_someip_config; /// Top-level element of the gateway configuration diff --git a/score/gateway_ipc_binding/BUILD b/score/gateway_ipc_binding/BUILD index dc1b8bd32..107d02b98 100644 --- a/score/gateway_ipc_binding/BUILD +++ b/score/gateway_ipc_binding/BUILD @@ -14,17 +14,6 @@ load("@rules_cc//cc:cc_library.bzl", "cc_library") load("@score_baselibs//score/language/safecpp:toolchain_features.bzl", "COMPILER_WARNING_FEATURES") -# Files carrying `// # req-Id:` markers, consumed by -# //score/gateway_ipc_binding/docs:docs_bundle via its code_targets attribute. -filegroup( - name = "requirement_marked_sources", - srcs = [ - "impl/binding_base.cpp", - "impl/shared_memory_slot_manager.cpp", - ], - visibility = ["//visibility:public"], -) - filegroup( name = "headers", srcs = glob([ diff --git a/score/gateway_ipc_binding/docs/BUILD b/score/gateway_ipc_binding/docs/BUILD index a529568ba..2bf2ea578 100644 --- a/score/gateway_ipc_binding/docs/BUILD +++ b/score/gateway_ipc_binding/docs/BUILD @@ -17,7 +17,6 @@ load("@score_docs_as_code//:docs.bzl", "docs_bundle") # load() of @score_docs_as_code. docs_bundle( name = "docs_bundle", - code_targets = ["//score/gateway_ipc_binding:requirement_marked_sources"], source_dir = "", visibility = ["//visibility:public"], ) diff --git a/score/gateway_ipc_binding/docs/index.rst b/score/gateway_ipc_binding/docs/index.rst index 59d5b5651..d0501472c 100644 --- a/score/gateway_ipc_binding/docs/index.rst +++ b/score/gateway_ipc_binding/docs/index.rst @@ -132,4 +132,3 @@ Further details shared_memory ipc_protocol - requirements/index diff --git a/score/gateway_ipc_binding/docs/requirements/index.rst b/score/gateway_ipc_binding/docs/requirements/index.rst deleted file mode 100644 index 7ae4968c8..000000000 --- a/score/gateway_ipc_binding/docs/requirements/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. - # ******************************************************************************* - # 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 - # ******************************************************************************* - -Requirements -############ - -.. toctree:: - - requirements diff --git a/score/gateway_ipc_binding/docs/requirements/requirements.rst b/score/gateway_ipc_binding/docs/requirements/requirements.rst deleted file mode 100644 index 06530e1e7..000000000 --- a/score/gateway_ipc_binding/docs/requirements/requirements.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. - # ******************************************************************************* - # 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 - # ******************************************************************************* - -Component Gateway IPC Binding Requirements -########################################## - -Functional Requirements ------------------------ - -.. comp_req:: Symmetric IPC binding with split control and payload planes - :id: comp_req__gateway_ipc_binding__ctrl_chan - :reqtype: Functional - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__gateway_ipc_binding - - The gateway IPC binding shall establish a symmetric client/server - control channel over ``score::message_passing`` and, once - established, allow either peer to offer services, request services, - subscribe to events, and publish event updates. Event payloads - shall travel through per-service shared-memory segments rather than - the control channel, referenced by a ``Shared_memory_handle`` and - released via ``Payload_consumed``. - -.. comp_req:: Fixed-size shared memory slot allocation - :id: comp_req__gateway_ipc_binding__slot_alloc - :reqtype: Functional - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__gateway_ipc_binding - - The binding shall allocate event payloads out of a - ``SharedMemorySlotManager`` backed by a ``FixedSizeContainer`` so - that payload allocation, transmission and reclaim happen without - dynamic allocation on the hot path and without heap fragmentation - in long-running gateway processes. - -.. comp_req:: Deferred connection setup for late peers - :id: comp_req__gateway_ipc_binding__pending_conn - :reqtype: Functional - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__gateway_ipc_binding - - When a peer requests a service that has not yet been offered, the - binding shall queue the connect attempt in ``PendingConnects`` and - complete the connection automatically once the corresponding - ``OfferService`` is received, so client and server startup order do - not need to be coordinated externally. - diff --git a/score/gateway_ipc_binding/impl/binding_base.cpp b/score/gateway_ipc_binding/impl/binding_base.cpp index baa3e5062..009f53bd7 100644 --- a/score/gateway_ipc_binding/impl/binding_base.cpp +++ b/score/gateway_ipc_binding/impl/binding_base.cpp @@ -11,8 +11,6 @@ * SPDX-License-Identifier: Apache-2.0 ********************************************************************************/ -// # req-Id: comp_req__gateway_ipc_binding__ctrl_chan -// # req-Id: comp_req__gateway_ipc_binding__pending_conn #include "binding_base.hpp" #include diff --git a/score/gateway_ipc_binding/impl/shared_memory_slot_manager.cpp b/score/gateway_ipc_binding/impl/shared_memory_slot_manager.cpp index f03b5ac03..85b4e56be 100644 --- a/score/gateway_ipc_binding/impl/shared_memory_slot_manager.cpp +++ b/score/gateway_ipc_binding/impl/shared_memory_slot_manager.cpp @@ -11,7 +11,6 @@ * SPDX-License-Identifier: Apache-2.0 ********************************************************************************/ -// # req-Id: comp_req__gateway_ipc_binding__slot_alloc #include "score/gateway_ipc_binding/shared_memory_slot_manager.hpp" #include diff --git a/score/gateway_ipc_binding/test/bidirectional_int_test.cpp b/score/gateway_ipc_binding/test/bidirectional_int_test.cpp index 06c2646f7..1bce47e56 100644 --- a/score/gateway_ipc_binding/test/bidirectional_int_test.cpp +++ b/score/gateway_ipc_binding/test/bidirectional_int_test.cpp @@ -42,9 +42,6 @@ using namespace std::chrono_literals; namespace score::gateway_ipc_binding { TEST_F(Gateway_ipc_binding_unconnected_integration_test, connect) { - RecordProperty("FullyVerifies", "comp_req__gateway_ipc_binding__ctrl_chan"); - RecordProperty("TestType", "requirements-based"); - RecordProperty("DerivationTechnique", "requirements-analysis"); // This test verifies that a client can connect to the server and receive a reply. // Start the server @@ -91,9 +88,6 @@ INSTANTIATE_TEST_SUITE_P(, Gateway_ipc_binding_connected_bidirectional_integrati readable_test_names); TEST_P(Gateway_ipc_binding_connected_bidirectional_integration_test, client_subscribes_to_event) { - RecordProperty("FullyVerifies", "comp_req__gateway_ipc_binding__pending_conn"); - RecordProperty("TestType", "requirements-based"); - RecordProperty("DerivationTechnique", "requirements-analysis"); std::promise event_subscription_change_promise; EXPECT_CALL(server.mock_event_subscription_change_cb, Call(_, event_id, socom::Event_state::subscribed)) diff --git a/score/gatewayd/BUILD.bazel b/score/gatewayd/BUILD.bazel index cdb50257e..7f571d64f 100644 --- a/score/gatewayd/BUILD.bazel +++ b/score/gatewayd/BUILD.bazel @@ -26,17 +26,6 @@ exports_files( ], ) -# Files carrying `// # req-Id:` markers, consumed by -# //score/gatewayd/docs:docs_bundle via its code_targets attribute. -filegroup( - name = "requirement_marked_sources", - srcs = [ - "impl/local_service_instance.cpp", - "impl/remote_service_instance.cpp", - ], - visibility = ["//visibility:public"], -) - cc_binary( name = "gatewayd", srcs = ["main.cpp"], diff --git a/score/gatewayd/docs/BUILD b/score/gatewayd/docs/BUILD index 3ec7e054e..8468d3310 100644 --- a/score/gatewayd/docs/BUILD +++ b/score/gatewayd/docs/BUILD @@ -17,7 +17,6 @@ load("@score_docs_as_code//:docs.bzl", "docs_bundle") # BUILD does not need to load @score_docs_as_code. docs_bundle( name = "docs_bundle", - code_targets = ["//score/gatewayd:requirement_marked_sources"], source_dir = "", visibility = ["//visibility:public"], ) diff --git a/score/gatewayd/docs/index.rst b/score/gatewayd/docs/index.rst index 3af4635da..62b7efdeb 100644 --- a/score/gatewayd/docs/index.rst +++ b/score/gatewayd/docs/index.rst @@ -21,8 +21,3 @@ Abstract ======== The gateway daemon. Bridges local IPC service instances with remote SOME/IP service instances across the ASIL boundary, handling service offers, requests, event subscriptions, and payload transfer. - -.. toctree:: - :maxdepth: 1 - - requirements/index diff --git a/score/gatewayd/docs/requirements/index.rst b/score/gatewayd/docs/requirements/index.rst deleted file mode 100644 index 7ae4968c8..000000000 --- a/score/gatewayd/docs/requirements/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. - # ******************************************************************************* - # 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 - # ******************************************************************************* - -Requirements -############ - -.. toctree:: - - requirements diff --git a/score/gatewayd/docs/requirements/requirements.rst b/score/gatewayd/docs/requirements/requirements.rst deleted file mode 100644 index 804433715..000000000 --- a/score/gatewayd/docs/requirements/requirements.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. - # ******************************************************************************* - # 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 - # ******************************************************************************* - -Component gatewayd Requirements -############################### - -Functional Requirements ------------------------ - -.. comp_req:: Bridge local IPC and remote SOME/IP service instances - :id: comp_req__gatewayd__local_remote_bridging - :reqtype: Functional - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__gatewayd - - ``gatewayd`` shall present local IPC service instances - (``LocalServiceInstance``) and remote SOME/IP service instances - (``RemoteServiceInstance``) to SOCom and shall forward service - offers, requests, event subscriptions and event updates between the - two sides so that an application client is unaware of the transport - layer. - -.. comp_req:: Publish locally hosted service instances on the SOME/IP network - :id: comp_req__gatewayd__publish_local_instance - :reqtype: Functional - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__gatewayd - - For every ``local_service_instance`` in the configuration - ``gatewayd`` shall instantiate a ``LocalServiceInstance`` that - translates local IPC service offers and event updates into SOME/IP - Service Discovery *Offer Service* entries and SOME/IP messages on - the network side. - -.. comp_req:: Subscribe to remote SOME/IP service instances on behalf of local clients - :id: comp_req__gatewayd__consume_remote_instance - :reqtype: Functional - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__gatewayd - - For every ``remote_service_instance`` in the configuration - ``gatewayd`` shall instantiate a ``RemoteServiceInstance`` that - consumes SOME/IP Service Discovery *Find/Offer* exchanges and - forwards received SOME/IP messages to any local IPC clients that - subscribed to that instance via SOCom. - diff --git a/score/gatewayd/impl/local_service_instance.cpp b/score/gatewayd/impl/local_service_instance.cpp index fdbfa09ae..b163e79f8 100644 --- a/score/gatewayd/impl/local_service_instance.cpp +++ b/score/gatewayd/impl/local_service_instance.cpp @@ -11,8 +11,6 @@ * SPDX-License-Identifier: Apache-2.0 ********************************************************************************/ -// # req-Id: comp_req__gatewayd__publish_local_instance -// # req-Id: comp_req__gatewayd__local_remote_bridging #include "local_service_instance.h" #include diff --git a/score/gatewayd/impl/remote_service_instance.cpp b/score/gatewayd/impl/remote_service_instance.cpp index f371c07c5..2b41c86bc 100644 --- a/score/gatewayd/impl/remote_service_instance.cpp +++ b/score/gatewayd/impl/remote_service_instance.cpp @@ -11,7 +11,6 @@ * SPDX-License-Identifier: Apache-2.0 ********************************************************************************/ -// # req-Id: comp_req__gatewayd__consume_remote_instance #include "remote_service_instance.h" #include diff --git a/score/serializer/BUILD.bazel b/score/serializer/BUILD.bazel index 4880a4db3..49f5546db 100644 --- a/score/serializer/BUILD.bazel +++ b/score/serializer/BUILD.bazel @@ -16,17 +16,6 @@ load("@rules_cc//cc:cc_library.bzl", "cc_library") load("@rules_cc//cc:cc_shared_library.bzl", "cc_shared_library") load("@rules_cc//cc:cc_test.bzl", "cc_test") -# Files carrying `// # req-Id:` markers, consumed by -# //score/serializer/docs:docs_bundle via its code_targets attribute. -filegroup( - name = "requirement_marked_sources", - srcs = [ - "null_serializer.cpp", - "serializer.h", - ], - visibility = ["//visibility:public"], -) - # Interface between gatewayd and the serializer library. The interface is defined as a C header file and the actual implementation is provided by a shared library which is loaded at runtime by gatewayd. cc_library( name = "interface", diff --git a/score/serializer/docs/BUILD b/score/serializer/docs/BUILD index 0fc4b0de2..8468d3310 100644 --- a/score/serializer/docs/BUILD +++ b/score/serializer/docs/BUILD @@ -17,7 +17,6 @@ load("@score_docs_as_code//:docs.bzl", "docs_bundle") # BUILD does not need to load @score_docs_as_code. docs_bundle( name = "docs_bundle", - code_targets = ["//score/serializer:requirement_marked_sources"], source_dir = "", visibility = ["//visibility:public"], ) diff --git a/score/serializer/docs/index.rst b/score/serializer/docs/index.rst index f0bde7a5e..5d9ce9505 100644 --- a/score/serializer/docs/index.rst +++ b/score/serializer/docs/index.rst @@ -21,8 +21,3 @@ Abstract ======== Serialization utilities. Currently provides a null-passthrough serializer for pre-serialized payloads so the fast path avoids double serialization. - -.. toctree:: - :maxdepth: 1 - - requirements/index diff --git a/score/serializer/docs/requirements/index.rst b/score/serializer/docs/requirements/index.rst deleted file mode 100644 index 7ae4968c8..000000000 --- a/score/serializer/docs/requirements/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. - # ******************************************************************************* - # 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 - # ******************************************************************************* - -Requirements -############ - -.. toctree:: - - requirements diff --git a/score/serializer/docs/requirements/requirements.rst b/score/serializer/docs/requirements/requirements.rst deleted file mode 100644 index 3f1fa9d00..000000000 --- a/score/serializer/docs/requirements/requirements.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. - # ******************************************************************************* - # 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 - # ******************************************************************************* - -Component Serializer Requirements -################################# - -Functional Requirements ------------------------ - -.. comp_req:: Null-passthrough serializer for pre-serialized payloads - :id: comp_req__serializer__null_passthrough - :reqtype: Functional - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__serializer - - The serializer shall provide a null-passthrough implementation - (``NullSerializer``) for payloads that arrive already serialized - (``PreSerializedData``), so the fast path can avoid a second - serialization pass while still satisfying the generic - ``Serializer`` interface. - -.. comp_req:: C ABI-stable serializer plugin interface - :id: comp_req__serializer__c_abi_plugin - :reqtype: Interface - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__serializer - - The serializer shall expose an ``extern "C"`` interface - (``score_com_serializer_serialize`` / ``_deserialize`` / ``_get`` / - ``_init`` / ``_deinit``) so different serializer implementations - (null, IDL-generated, third-party) can be loaded as ABI-compatible - plugins without recompiling the gateway. - -.. comp_req:: Per-element serializer lookup by service type and element kind - :id: comp_req__serializer__element_lookup - :reqtype: Interface - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__serializer - - ``score_com_serializer_get`` shall return the serializer matching a - given ``service_type`` and element kind (``event``, ``field``, - ``method_call``, ``method_response``) so events, fields and - request/response method payloads can each be (de)serialized with - the right layout without additional dispatch in the caller. - diff --git a/score/serializer/null_serializer.cpp b/score/serializer/null_serializer.cpp index 61e943abc..4cf1278c1 100644 --- a/score/serializer/null_serializer.cpp +++ b/score/serializer/null_serializer.cpp @@ -14,10 +14,6 @@ /// @file /// This file provides a "serializer" which actually doesn't serialize and just copies the memory. -// # req-Id: comp_req__serializer__null_passthrough -// # req-Id: comp_req__serializer__c_abi_plugin -// # req-Id: comp_req__serializer__element_lookup - #include #include #include diff --git a/score/serializer/null_serializer_test.cpp b/score/serializer/null_serializer_test.cpp index dbb1ef073..0c7d832d9 100644 --- a/score/serializer/null_serializer_test.cpp +++ b/score/serializer/null_serializer_test.cpp @@ -131,10 +131,6 @@ TEST_F(NullSerializer_test, init_with_empty_file_fails) { // --- score_com_serializer_get --- TEST_F(NullSerializer_test, get_event_serializer_succeeds) { - RecordProperty("FullyVerifies", - "comp_req__serializer__element_lookup, comp_req__serializer__c_abi_plugin"); - RecordProperty("TestType", "requirements-based"); - RecordProperty("DerivationTechnique", "requirements-analysis"); const score_com_serializer* serializer = nullptr; std::string service(kTestServiceTypeName); std::string element(kTestEventName); diff --git a/score/socom/BUILD b/score/socom/BUILD index 0425648a3..3477ea085 100644 --- a/score/socom/BUILD +++ b/score/socom/BUILD @@ -14,18 +14,6 @@ load("@rules_cc//cc:cc_library.bzl", "cc_library") load("@score_baselibs//score/language/safecpp:toolchain_features.bzl", "COMPILER_WARNING_FEATURES") -# Files carrying `// # req-Id:` markers, consumed by -# //score/socom/docs:docs_bundle via its code_targets attribute. -filegroup( - name = "requirement_marked_sources", - srcs = [ - "impl/runtime_impl.cpp", - "impl/service_identifier.cpp", - "impl/string_registry.cpp", - ], - visibility = ["//visibility:public"], -) - filegroup( name = "headers", srcs = glob([ diff --git a/score/socom/docs/BUILD b/score/socom/docs/BUILD index 3c49321c7..d0ae37499 100644 --- a/score/socom/docs/BUILD +++ b/score/socom/docs/BUILD @@ -17,7 +17,6 @@ load("@score_docs_as_code//:docs.bzl", "docs_bundle") # load() of @score_docs_as_code. docs_bundle( name = "docs_bundle", - code_targets = ["//score/socom:requirement_marked_sources"], source_dir = "", visibility = ["//visibility:public"], ) diff --git a/score/socom/docs/index.rst b/score/socom/docs/index.rst index 2423bd23c..e1d4a7172 100644 --- a/score/socom/docs/index.rst +++ b/score/socom/docs/index.rst @@ -32,4 +32,3 @@ abstraction layer for SOME/IP communication in the S-CORE framework. :maxdepth: 1 design/index - requirements/index diff --git a/score/socom/docs/requirements/index.rst b/score/socom/docs/requirements/index.rst deleted file mode 100644 index 7ae4968c8..000000000 --- a/score/socom/docs/requirements/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. - # ******************************************************************************* - # 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 - # ******************************************************************************* - -Requirements -############ - -.. toctree:: - - requirements diff --git a/score/socom/docs/requirements/requirements.rst b/score/socom/docs/requirements/requirements.rst deleted file mode 100644 index 835200ab6..000000000 --- a/score/socom/docs/requirements/requirements.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. - # ******************************************************************************* - # 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 - # ******************************************************************************* - -Component SOCom Requirements -############################ - -Functional Requirements ------------------------ - -.. comp_req:: Service-oriented communication runtime - :id: comp_req__socom__service_runtime - :reqtype: Interface - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__socom - - SOCom shall expose ``Runtime``, ``ClientConnector`` and - ``ServerConnector`` APIs so that services can be offered, requested, - subscribed to, and their event/method payloads exchanged through a - pluggable transport backend (gateway IPC binding, mock, or any - future backend) without exposing the transport details to the - application. - -.. comp_req:: Stable service and method identity across processes - :id: comp_req__socom__service_identity - :reqtype: Interface - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__socom - - SOCom shall provide value types (``ServiceIdentifier``, - ``Method``, ``ServiceInterfaceDefinition``) that identify a - service and its methods/events in a way that is stable across - process boundaries and independent of local pointer values, so - that the same identity round-trips faithfully through the IPC - binding and the SOME/IP wire. - -.. comp_req:: String interning for repeated protocol identifiers - :id: comp_req__socom__string_registry - :reqtype: Non-Functional - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__socom - - SOCom shall provide a ``StringRegistry`` that interns repeated - protocol strings (service type names, event/method names) so that - the runtime and transport layer can refer to them by a small - integer id instead of resending the full string on every message. - diff --git a/score/socom/impl/runtime_impl.cpp b/score/socom/impl/runtime_impl.cpp index d171ef7d8..29b3b1427 100644 --- a/score/socom/impl/runtime_impl.cpp +++ b/score/socom/impl/runtime_impl.cpp @@ -11,7 +11,6 @@ * SPDX-License-Identifier: Apache-2.0 ********************************************************************************/ -// # req-Id: comp_req__socom__service_runtime #include "runtime_impl.hpp" #include diff --git a/score/socom/impl/service_identifier.cpp b/score/socom/impl/service_identifier.cpp index 3c65cffc9..d84eb383e 100644 --- a/score/socom/impl/service_identifier.cpp +++ b/score/socom/impl/service_identifier.cpp @@ -11,7 +11,6 @@ * SPDX-License-Identifier: Apache-2.0 ********************************************************************************/ -// # req-Id: comp_req__socom__service_identity #include "service_identifier.hpp" #include diff --git a/score/socom/impl/string_registry.cpp b/score/socom/impl/string_registry.cpp index 7f4a6bafd..245e06974 100644 --- a/score/socom/impl/string_registry.cpp +++ b/score/socom/impl/string_registry.cpp @@ -11,7 +11,6 @@ * SPDX-License-Identifier: Apache-2.0 ********************************************************************************/ -// # req-Id: comp_req__socom__string_registry #include "score/socom/string_registry.hpp" #include diff --git a/score/socom/test/unit/string_registry_tests.cpp b/score/socom/test/unit/string_registry_tests.cpp index ccf04fed7..ebc590a02 100644 --- a/score/socom/test/unit/string_registry_tests.cpp +++ b/score/socom/test/unit/string_registry_tests.cpp @@ -21,9 +21,6 @@ namespace score::socom { TEST(StringRegistryTest, InsertMultipleStrings) { - RecordProperty("FullyVerifies", "comp_req__socom__string_registry"); - RecordProperty("TestType", "requirements-based"); - RecordProperty("DerivationTechnique", "requirements-analysis"); String_registry registry; /// Verify the existence of the type cara::core::util::String_registry interface. diff --git a/score/someip/BUILD.bazel b/score/someip/BUILD.bazel index e9d982a34..1851ae6e5 100644 --- a/score/someip/BUILD.bazel +++ b/score/someip/BUILD.bazel @@ -17,17 +17,6 @@ Common types and constants shared across the SOME/IP gateway components. load("@rules_cc//cc:cc_library.bzl", "cc_library") -# Files carrying `// # req-Id:` markers, consumed by -# //score/someip/docs:docs_bundle via its code_targets attribute. -filegroup( - name = "requirement_marked_sources", - srcs = [ - "constants.h", - "types.h", - ], - visibility = ["//visibility:public"], -) - cc_library( name = "someip", hdrs = [ diff --git a/score/someip/constants.h b/score/someip/constants.h index d7b4887cc..6d29be930 100644 --- a/score/someip/constants.h +++ b/score/someip/constants.h @@ -16,9 +16,6 @@ #include "score/someip/types.h" -// # req-Id: comp_req__someip__protocol_types -// # req-Id: comp_req__someip__protocol_limits - namespace score::someip { // ============================================================================= diff --git a/score/someip/docs/BUILD b/score/someip/docs/BUILD index 1110f941f..8468d3310 100644 --- a/score/someip/docs/BUILD +++ b/score/someip/docs/BUILD @@ -17,7 +17,6 @@ load("@score_docs_as_code//:docs.bzl", "docs_bundle") # BUILD does not need to load @score_docs_as_code. docs_bundle( name = "docs_bundle", - code_targets = ["//score/someip:requirement_marked_sources"], source_dir = "", visibility = ["//visibility:public"], ) diff --git a/score/someip/docs/index.rst b/score/someip/docs/index.rst index 31a5c3f3b..ee7c071cd 100644 --- a/score/someip/docs/index.rst +++ b/score/someip/docs/index.rst @@ -29,8 +29,3 @@ Abstract ======== SOME/IP protocol type and constant definitions (message header fields, method/event IDs, error codes) per the Open SOME/IP protocol specification. - -.. toctree:: - :maxdepth: 1 - - requirements/index diff --git a/score/someip/docs/requirements/index.rst b/score/someip/docs/requirements/index.rst deleted file mode 100644 index 7ae4968c8..000000000 --- a/score/someip/docs/requirements/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. - # ******************************************************************************* - # 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 - # ******************************************************************************* - -Requirements -############ - -.. toctree:: - - requirements diff --git a/score/someip/docs/requirements/requirements.rst b/score/someip/docs/requirements/requirements.rst deleted file mode 100644 index f1a8db0c8..000000000 --- a/score/someip/docs/requirements/requirements.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. - # ******************************************************************************* - # 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 - # ******************************************************************************* - -Component someip Requirements -############################# - -Functional Requirements ------------------------ - -.. comp_req:: SOME/IP protocol type and constant definitions - :id: comp_req__someip__protocol_types - :reqtype: Interface - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__someip - - The ``someip`` library shall provide the header field types - (``types.h``), protocol constants (``constants.h``) and error codes - (``someip_error.h``) required by the Open SOME/IP protocol - specification, so that downstream components (``someipd``, - ``gatewayd``) share a single canonical definition of the on-wire - protocol elements. - -.. comp_req:: 16-bit SOME/IP identifier types - :id: comp_req__someip__id_widths - :reqtype: Interface - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__someip - - ``types.h`` shall define ``ServiceId``, ``InstanceId``, ``EventId`` - and ``EventGroupId`` as ``std::uint16_t`` so all in-process - handling of SOME/IP identifiers matches the 16-bit widths mandated - by the SOME/IP header layout in the Open SOME/IP specification. - -.. comp_req:: Wildcard instance id and maximum message size - :id: comp_req__someip__protocol_limits - :reqtype: Interface - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__someip - - ``constants.h`` shall expose the wildcard instance id - (``kAnyInstance = 0xFFFF``), the SOME/IP header size - (``kSomeipFullHeaderSize = 16``) and the per-message size cap - (``kMaxMessageSize = 1500``) chosen to keep single SOME/IP messages - within a standard Ethernet MTU and avoid IP fragmentation. - diff --git a/score/someip/types.h b/score/someip/types.h index 3f0eaf1f8..bda10c165 100644 --- a/score/someip/types.h +++ b/score/someip/types.h @@ -17,8 +17,6 @@ #include #include -// # req-Id: comp_req__someip__id_widths - namespace score::someip { using ServiceId = std::uint16_t; diff --git a/score/someipd/BUILD.bazel b/score/someipd/BUILD.bazel index 264d53075..56e9ca24d 100644 --- a/score/someipd/BUILD.bazel +++ b/score/someipd/BUILD.bazel @@ -19,17 +19,6 @@ load("@bazel_skylib//rules:native_binary.bzl", "native_binary") load("@rules_cc//cc:cc_binary.bzl", "cc_binary") load("@rules_cc//cc:cc_library.bzl", "cc_library") -# Files carrying `// # req-Id:` markers, consumed by -# //score/someipd/docs:docs_bundle via its code_targets attribute. -filegroup( - name = "requirement_marked_sources", - srcs = [ - "impl/local_network_service.cpp", - "impl/routing.cpp", - ], - visibility = ["//visibility:public"], -) - # ============================================================================ # Main Binary # ============================================================================ diff --git a/score/someipd/docs/BUILD b/score/someipd/docs/BUILD index c7b8057e8..8468d3310 100644 --- a/score/someipd/docs/BUILD +++ b/score/someipd/docs/BUILD @@ -17,7 +17,6 @@ load("@score_docs_as_code//:docs.bzl", "docs_bundle") # BUILD does not need to load @score_docs_as_code. docs_bundle( name = "docs_bundle", - code_targets = ["//score/someipd:requirement_marked_sources"], source_dir = "", visibility = ["//visibility:public"], ) diff --git a/score/someipd/docs/index.rst b/score/someipd/docs/index.rst index 7d8255d31..ed59483b6 100644 --- a/score/someipd/docs/index.rst +++ b/score/someipd/docs/index.rst @@ -21,8 +21,3 @@ Abstract ======== The SOME/IP daemon. Wraps the SOME/IP protocol stack, handles Service Discovery, and routes messages between remote peers and local IPC clients. - -.. toctree:: - :maxdepth: 1 - - requirements/index diff --git a/score/someipd/docs/requirements/index.rst b/score/someipd/docs/requirements/index.rst deleted file mode 100644 index 7ae4968c8..000000000 --- a/score/someipd/docs/requirements/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. - # ******************************************************************************* - # 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 - # ******************************************************************************* - -Requirements -############ - -.. toctree:: - - requirements diff --git a/score/someipd/docs/requirements/requirements.rst b/score/someipd/docs/requirements/requirements.rst deleted file mode 100644 index 492568488..000000000 --- a/score/someipd/docs/requirements/requirements.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. - # ******************************************************************************* - # 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 - # ******************************************************************************* - -Component someipd Requirements -############################## - -Functional Requirements ------------------------ - -.. comp_req:: SOME/IP Service Discovery handling - :id: comp_req__someipd__sd_protocol - :reqtype: Functional - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__someipd - - ``someipd`` shall implement the SOME/IP Service Discovery (SD) - protocol entries (``FindService``, ``OfferService``, - ``StopOfferService``, ``Subscribe``, ``StopSubscribe``, - ``SubscribeAck``, ``SubscribeNack``) needed by the Open SOME/IP-SD - specification, so peers can discover and subscribe to SOME/IP - services offered by this host. - -.. comp_req:: Route SOME/IP traffic between remote peers and local clients - :id: comp_req__someipd__remote_local_routing - :reqtype: Functional - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__someipd - - ``someipd`` shall run the SOME/IP protocol stack and route messages - between remote peers on the network (``RemoteNetworkService``) and - local IPC clients (``LocalNetworkService``) via its ``Routing`` - subsystem, translating between on-wire SOME/IP frames and the - internal IPC representation without exposing the network to local - clients. - -.. comp_req:: Local-only network service for gateway-hosted instances - :id: comp_req__someipd__local_network_service - :reqtype: Functional - :security: NO - :safety: QM - :status: valid - :version: 1 - :satisfied_by: comp__someipd - - The ``LocalNetworkService`` role shall handle SOME/IP messages - whose target instance is locally hosted by the gateway, so that - requests originating from remote peers reach the correct local - application without traversing an additional network hop. - diff --git a/score/someipd/impl/local_network_service.cpp b/score/someipd/impl/local_network_service.cpp index 5e211a3d3..335345795 100644 --- a/score/someipd/impl/local_network_service.cpp +++ b/score/someipd/impl/local_network_service.cpp @@ -11,7 +11,6 @@ * SPDX-License-Identifier: Apache-2.0 ********************************************************************************/ -// # req-Id: comp_req__someipd__local_network_service #include "local_network_service.h" #include diff --git a/score/someipd/impl/routing.cpp b/score/someipd/impl/routing.cpp index dde174438..1a15fe77f 100644 --- a/score/someipd/impl/routing.cpp +++ b/score/someipd/impl/routing.cpp @@ -11,8 +11,6 @@ * SPDX-License-Identifier: Apache-2.0 ********************************************************************************/ -// # req-Id: comp_req__someipd__remote_local_routing -// # req-Id: comp_req__someipd__sd_protocol #include "routing.h" #include From fd1294151d671a1c6ce6d5e96cd543c22ff5a6bc Mon Sep 17 00:00:00 2001 From: Gabriel Pinheiro Date: Mon, 7 Sep 2026 15:37:53 +0100 Subject: [PATCH 7/9] ci: add workflow that comments traceability gate on PRs --- .github/workflows/ci.yml | 7 +- .github/workflows/quality_pack-publish.yml | 122 ++++++++++++++++++ ...lity_pack_comment.yml => quality_pack.yml} | 57 +++----- 3 files changed, 139 insertions(+), 47 deletions(-) create mode 100644 .github/workflows/quality_pack-publish.yml rename .github/workflows/{quality_pack_comment.yml => quality_pack.yml} (54%) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 714099357..75a5c9e35 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -38,12 +38,9 @@ jobs: docs: secrets: inherit uses: ./.github/workflows/docs.yml - quality_pack_comment: + quality_pack: secrets: inherit - permissions: - contents: read - pull-requests: write - uses: ./.github/workflows/quality_pack_comment.yml + uses: ./.github/workflows/quality_pack.yml static-code-analysis: secrets: inherit uses: ./.github/workflows/static-code-analysis.yml diff --git a/.github/workflows/quality_pack-publish.yml b/.github/workflows/quality_pack-publish.yml new file mode 100644 index 000000000..013172bab --- /dev/null +++ b/.github/workflows/quality_pack-publish.yml @@ -0,0 +1,122 @@ +# ******************************************************************************* +# 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 +# +# ******************************************************************************* + +# Waits for the CI workflow of a pull request, downloads the traceability gate +# artifact produced by quality_pack_comment.yml, and posts (or edits) a +# comment on the pull request with the gate summary and pass/fail status. +# +# Runs via workflow_run so that pull requests opened from forks — which get a +# read-only GITHUB_TOKEN and cannot write comments themselves — still get a +# comment posted by this workflow, which runs with the base repo's token. + +name: Publish Quality Pack Comment + +on: + workflow_run: + workflows: ["CI"] + types: + - completed + +jobs: + quality-pack-comment: + name: Comment traceability gate on the pull request + if: github.event.workflow_run.event == 'pull_request' + runs-on: ubuntu-latest + permissions: + actions: read # list + download the artifacts of the triggering workflow run + pull-requests: write # comment on the pull request + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + RUN_ID: ${{ github.event.workflow_run.id }} + steps: + - name: Resolve pull request number + id: metadata + env: + HEAD_REPO_OWNER: ${{ github.event.workflow_run.head_repository.owner.login }} + PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number || '' }} + REF_NAME: ${{ github.event.workflow_run.head_branch }} + run: | + set -euo pipefail + + if [[ "$PR_NUMBER" == "null" ]]; then + PR_NUMBER="" + fi + + # fork-origin workflow_run payloads do not include pull_requests[] + if [[ -z "$PR_NUMBER" && -n "$HEAD_REPO_OWNER" && -n "$REF_NAME" ]]; then + PR_NUMBER="$(gh api \ + "repos/${REPO}/pulls?state=all&head=${HEAD_REPO_OWNER}:${REF_NAME}" \ + --jq '.[0].number // empty' || true)" + fi + + if [[ -z "$PR_NUMBER" ]]; then + echo "Could not determine PR number for pull_request event." >&2 + exit 1 + fi + + echo "pr_number=$PR_NUMBER" >> "$GITHUB_OUTPUT" + + - name: Download quality pack artifact + id: download + continue-on-error: true + uses: actions/download-artifact@v4 + with: + name: quality-pack-metrics + path: _quality_pack_dl + github-token: ${{ github.token }} + repository: ${{ github.repository }} + run-id: ${{ github.event.workflow_run.id }} + + - name: Render comment body + id: render + run: | + set -euo pipefail + + GATE_FILE=_quality_pack_dl/_quality_pack/gate.txt + if [[ -f "$GATE_FILE" ]]; then + if grep -q "Threshold check passed." "$GATE_FILE"; then + status="**PASS**" + else + status="**FAIL**" + fi + gate_body=$(cat "$GATE_FILE") + else + status="**UNAVAILABLE**" + gate_body="No traceability gate output was produced by the CI run." + fi + + { + echo "Quality pack traceability report for this pull request:" + echo + echo "Status: $status ([workflow run](${{ github.event.workflow_run.html_url }}))" + echo + echo '```text' + echo "$gate_body" + echo '```' + } > comment.md + + - name: Find existing PR comment + uses: peter-evans/find-comment@b30e6a3c0ed37e7c023ccd3f1db5c6c0b0c23aad # v4.0.0 + id: fc + with: + issue-number: ${{ steps.metadata.outputs.pr_number }} + comment-author: "github-actions[bot]" + body-includes: Quality pack traceability report for this pull request + + - name: Comment on PR with traceability gate summary + uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9 # v5.0.0 + with: + issue-number: ${{ steps.metadata.outputs.pr_number }} + comment-id: ${{ steps.fc.outputs.comment-id }} + edit-mode: replace + body-path: comment.md diff --git a/.github/workflows/quality_pack_comment.yml b/.github/workflows/quality_pack.yml similarity index 54% rename from .github/workflows/quality_pack_comment.yml rename to .github/workflows/quality_pack.yml index 83fc9b149..f8a63d8fd 100644 --- a/.github/workflows/quality_pack_comment.yml +++ b/.github/workflows/quality_pack.yml @@ -11,21 +11,21 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -# Builds the docs, runs the upstream //:traceability_gate against the resulting -# _build/metrics.json, and posts (or edits) a sticky PR comment with the gate -# output and pass/fail status. +# Builds the docs and runs the upstream //:traceability_gate against the +# resulting _build/metrics.json, then uploads the gate output as an artifact. # -# The comment step is best-effort: PRs from forks get a read-only GITHUB_TOKEN -# and the sticky-comment action will fail with 403 — marked continue-on-error -# so those PRs still surface the numbers via the job log and artifact. +# This workflow does NOT comment on the PR — see quality_pack-publish.yml for +# the elevated-permissions companion that downloads the artifact and posts. +# The split is required so that pull requests opened from forks (which get a +# read-only GITHUB_TOKEN) still get a comment. -name: Quality pack coverage comment +name: Quality pack coverage on: workflow_call: jobs: - quality-pack-comment: + quality-pack: runs-on: ubuntu-24.04 steps: - uses: eclipse-score/more-disk-space@v1 @@ -50,51 +50,24 @@ jobs: # Thresholds default to 0 while comp_req coverage is being (re-)built up # against the SOME/IP protocol spec. Raise the --min-* flags as # links land, so the gate never regresses without a follow-up ticket. + # --need-type=comp_req scopes the gate to component requirements; + # feat_req / stkh_req live upstream in eclipse-score/score and would + # otherwise pull the numbers to zero and flap the gate. - name: Run traceability gate - id: gate continue-on-error: true run: | - mkdir -p .llm_tmp - # --need-type=comp_req scopes the gate to component requirements; - # feat_req / stkh_req live upstream in eclipse-score/score and would - # otherwise pull the numbers to zero and flap the gate. + mkdir -p _quality_pack bazel run //:traceability_gate -- \ --metrics-json "$PWD/_build/metrics.json" \ --need-type=comp_req \ - > .llm_tmp/gate.txt - - name: Render sticky comment body - run: | - if [ "${{ steps.gate.outcome }}" = "success" ]; then - status="**PASS**" - else - status="**FAIL**" - fi - { - echo '' - echo "### Quality pack traceability — gate: $status" - echo - echo '```text' - cat .llm_tmp/gate.txt - echo '```' - echo - echo "Produced by \`//:traceability_gate\` against \`_build/metrics.json\`." - } > .llm_tmp/comment.md - cat .llm_tmp/comment.md - - name: Upload metrics + gate output + > _quality_pack/gate.txt + - name: Upload quality pack artifact if: always() uses: actions/upload-artifact@v7 with: name: quality-pack-metrics path: | _build/metrics.json - .llm_tmp/gate.txt - .llm_tmp/comment.md + _quality_pack/gate.txt if-no-files-found: warn retention-days: 14 - - name: Post sticky PR comment - if: github.event_name == 'pull_request' - continue-on-error: true - uses: marocchino/sticky-pull-request-comment@52423e01640425a022ef5fd42c6fb5f633a02728 # v2.9.1 - with: - header: quality-pack-coverage - path: .llm_tmp/comment.md From 461ff906bd461e074c4e6980da568ffad22aab19 Mon Sep 17 00:00:00 2001 From: Gabriel Pinheiro Date: Wed, 9 Sep 2026 15:35:44 +0100 Subject: [PATCH 8/9] ci: require quality_pack to pass before merge --- .github/workflows/ci.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 75a5c9e35..e02ef619b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -58,6 +58,7 @@ jobs: - build_and_test_cross_compilation - coverage - docs + - quality_pack - static-code-analysis permissions: {} runs-on: ubuntu-latest From c23da1ef37d6ececdcec254491660ddc40d2b321 Mon Sep 17 00:00:00 2001 From: Gabriel Pinheiro Date: Thu, 10 Sep 2026 12:15:40 +0100 Subject: [PATCH 9/9] ci(quality-pack): install Graphviz and fix publish workflow header --- .github/workflows/quality_pack-publish.yml | 1 + .github/workflows/quality_pack.yml | 2 ++ 2 files changed, 3 insertions(+) diff --git a/.github/workflows/quality_pack-publish.yml b/.github/workflows/quality_pack-publish.yml index 013172bab..cbc067614 100644 --- a/.github/workflows/quality_pack-publish.yml +++ b/.github/workflows/quality_pack-publish.yml @@ -8,6 +8,7 @@ # 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 # ******************************************************************************* # Waits for the CI workflow of a pull request, downloads the traceability gate diff --git a/.github/workflows/quality_pack.yml b/.github/workflows/quality_pack.yml index f8a63d8fd..b7cb63a5d 100644 --- a/.github/workflows/quality_pack.yml +++ b/.github/workflows/quality_pack.yml @@ -43,6 +43,8 @@ jobs: unique-cache-name: ${{ github.job }} - name: Allow linux-sandbox uses: eclipse-score/cicd-actions/unblock-user-namespace-for-linux-sandbox@212bbf86267e9381da9d2daf962d12f6feafbc90 # v0.0.2 + - name: Install Graphviz (required by PlantUML for non-sequence diagrams) + run: sudo apt-get update && sudo apt-get install -y graphviz - name: Build unit + component tests (needed for test links) run: bazel test //:unit_tests //:component_tests - name: Build docs