Infrastructure/Process Workshop "Docs-As-Code"

[anmittag]

Intro

The Eclipse S-CORE project has decided to follow a docs-as-code approach as the common basis for generating and maintaining the project’s engineering documentation and evidence. This includes requirements, architecture, test specifications and results, quality results, and end-to-end traceability.
A blocking issue has emerged: some S-CORE modules e.g. COM, CFG currently do not, or cannot, follow this approach consistently. As a result, the project cannot yet guarantee a uniform, reproducible, and auditable evidence chain across all contributed modules.
This is not only a documentation concern. It creates a material risk for distributors that integrate S-CORE into a commercial offering and must ultimately qualify the resulting distribution. Missing or incompatible evidence increases the effort required to reconstruct traceability, assess quality and completeness, justify deviations, and provide qualification or certification evidence.

0: Big Picture

• Meta Model: https://eclipse-score.github.io/process_description/main/_images/score_building_blocks_meta_model.drawio.svg
• Work Products Overview: https://eclipse-score.github.io/process_description/main/workproducts/index.html

1: Identification of the Docs-As-Code Meta-Model Coverage

• https://eclipse-score.github.io/docs-as-code/main/reference/metamodel/index.html

2: Identification of the TRLC/Dependable Elements Meta-Model Coverage incl. connection to S-CORE certification, S-CORE Tooling, S-CORE Process

2.1: Metamodel drift and verification differences

3: How to deal with the heterogeneous situation for Milestone S-CORE 1.0

3.1: Documentation generation

3.2: Handling reports and checklists

• https://eclipse-score.github.io/reference_integration/main/verification_report/index.html

4: Safety Aspects

[FScholPer]

Drift report

Metamodel Drift Report

Summary

Severity	Findings
error	21
warning	41
info	4

Mapped type: AoU → aou_req

ID	Severity	Field / option	Message
ENUM_VALUE_REJECTED	error	safety	TRLC enum literal 'D' maps to 'ASIL_D', which does not match need option 'safety' pattern '^(QM|ASIL_B)$'.
MANDATORY_OPTION_MISSING	error	reqtype	Mandatory need option 'reqtype' has no mapped TRLC field.
MANDATORY_OPTION_MISSING	error	security	Mandatory need option 'security' has no mapped TRLC field.
NEED_VALUE_UNREPRESENTABLE	warning	status	Need option 'status' permits 'valid_inspected', but no TRLC value maps to it.
TRLC_FIELD_UNMAPPED	warning	note	TRLC field 'note' is not exported or explicitly ignored.
TRLC_FIELD_UNMAPPED	warning	root_causes	TRLC field 'root_causes' is not exported or explicitly ignored.

Mapped type: AssumedSystemReq → stkh_req

ID	Severity	Field / option	Message
ENUM_VALUE_REJECTED	error	safety	TRLC enum literal 'D' maps to 'ASIL_D', which does not match need option 'safety' pattern '^(QM|ASIL_B)$'.
MANDATORY_OPTION_MISSING	error	reqtype	Mandatory need option 'reqtype' has no mapped TRLC field.
MANDATORY_OPTION_MISSING	error	security	Mandatory need option 'security' has no mapped TRLC field.
MANDATORY_OPTION_MISSING	error	valid_from	Mandatory need option 'valid_from' has no mapped TRLC field.
NEED_VALUE_UNREPRESENTABLE	warning	status	Need option 'status' permits 'valid_inspected', but no TRLC value maps to it.
TRLC_FIELD_UNMAPPED	warning	note	TRLC field 'note' is not exported or explicitly ignored.

Mapped type: CompReq → comp_req

ID	Severity	Field / option	Message
ENUM_VALUE_REJECTED	error	safety	TRLC enum literal 'D' maps to 'ASIL_D', which does not match need option 'safety' pattern '^(QM|ASIL_B)$'.
LINK_MULTIPLICITY	info	derived_from	TRLC field 'derived_from' has minimum multiplicity 1; need link 'derived_from' is optional.
LINK_TARGET_REJECTED	error	derived_from	TRLC target 'AoU' maps to 'aou_req', which is not allowed by need link 'derived_from' (feat_req).
LINK_TARGET_REJECTED	error	derived_from	TRLC target 'AssumedSystemReq' maps to 'stkh_req', which is not allowed by need link 'derived_from' (feat_req).
LINK_TARGET_UNMAPPED	warning	derived_from	TRLC link target 'RootCause' has no exported need type. Reason: No need type; comp_saf_fmea only has a free-text root_cause option.
MANDATORY_LINK_MISSING	error	satisfied_by	Mandatory need link 'satisfied_by' has no mapped TRLC field.
MANDATORY_OPTION_MISSING	error	reqtype	Mandatory need option 'reqtype' has no mapped TRLC field.
MANDATORY_OPTION_MISSING	error	security	Mandatory need option 'security' has no mapped TRLC field.
NEED_VALUE_UNREPRESENTABLE	warning	status	Need option 'status' permits 'valid_inspected', but no TRLC value maps to it.
TRLC_FIELD_UNMAPPED	warning	note	TRLC field 'note' is not exported or explicitly ignored.

Mapped type: FailureMode → comp_saf_fmea

ID	Severity	Field / option	Message
MANDATORY_LINK_MISSING	error	violates	Mandatory need link 'violates' has no mapped TRLC field.
MANDATORY_OPTION_MISSING	error	fault_id	Mandatory need option 'fault_id' has no mapped TRLC field.
MANDATORY_OPTION_MISSING	error	sufficient	Mandatory need option 'sufficient' has no mapped TRLC field.
TRLC_FIELD_UNMAPPED	warning	guidewords	TRLC field 'guidewords' is not exported or explicitly ignored.
TRLC_FIELD_UNMAPPED	warning	interface	TRLC field 'interface' is not exported or explicitly ignored.
TRLC_FIELD_UNMAPPED	warning	note	TRLC field 'note' is not exported or explicitly ignored.
TRLC_FIELD_UNMAPPED	warning	rationale	TRLC field 'rationale' is not exported or explicitly ignored.
TRLC_FIELD_UNMAPPED	warning	safety	TRLC field 'safety' is not exported or explicitly ignored.

Mapped type: FeatReq → feat_req

ID	Severity	Field / option	Message
ENUM_VALUE_REJECTED	error	safety	TRLC enum literal 'D' maps to 'ASIL_D', which does not match need option 'safety' pattern '^(QM|ASIL_B)$'.
LINK_MULTIPLICITY	info	derived_from	TRLC field 'derived_from' has minimum multiplicity 1; need link 'derived_from' is optional.
MANDATORY_LINK_MISSING	error	satisfied_by	Mandatory need link 'satisfied_by' has no mapped TRLC field.
MANDATORY_OPTION_MISSING	error	reqtype	Mandatory need option 'reqtype' has no mapped TRLC field.
MANDATORY_OPTION_MISSING	error	security	Mandatory need option 'security' has no mapped TRLC field.
MANDATORY_OPTION_MISSING	error	valid_from	Mandatory need option 'valid_from' has no mapped TRLC field.
NEED_VALUE_UNREPRESENTABLE	warning	status	Need option 'status' permits 'valid_inspected', but no TRLC value maps to it.
TRLC_FIELD_UNMAPPED	warning	note	TRLC field 'note' is not exported or explicitly ignored.

Global findings

ID	Severity	Field / option	Message
TRLC_TYPE_NOT_EXPORTED	info		Concrete TRLC type 'Mitigation' is intentionally not exported: No need type for safety measures that argue a root cause away.
TRLC_TYPE_NOT_EXPORTED	info		Concrete TRLC type 'RootCause' is intentionally not exported: No need type; comp_saf_fmea only has a free-text root_cause option.

Compared RSL copy: communication

ID	Severity	Field / option	Message
RSL_COPY_FIELD_ADDED	warning	safety	Field 'safety' exists on Requirement in the copy but not in the primary RSL.
RSL_COPY_FIELD_CHANGED	warning		Parent of 'AssumedSystemReq' changed from 'RequirementSafety' to 'Requirement'.
RSL_COPY_FIELD_CHANGED	warning		Parent of 'CompReq' changed from 'RequirementSafety' to 'Requirement'.
RSL_COPY_FIELD_CHANGED	warning	derived_from	Type of CompReq.derived_from changed from 'CompReqSourceId[1..]' to 'FeatReqId[1..]'.
RSL_COPY_FIELD_CHANGED	warning		Parent of 'FeatReq' changed from 'RequirementSafety' to 'Requirement'.
RSL_COPY_FIELD_CHANGED	warning	description	Type of Requirement.description changed from 'Markup_String' to 'String'.
RSL_COPY_TYPE_ADDED	warning		Type 'StdReq' exists in the copy but not in the primary RSL.
RSL_COPY_TYPE_REMOVED	warning		Type 'AoU' exists in the primary RSL but not in the copy.
RSL_COPY_TYPE_REMOVED	warning		Type 'FailureMode' exists in the primary RSL but not in the copy.
RSL_COPY_TYPE_REMOVED	warning		Type 'Mitigation' exists in the primary RSL but not in the copy.
RSL_COPY_TYPE_REMOVED	warning		Type 'RequirementSafety' exists in the primary RSL but not in the copy.
RSL_COPY_TYPE_REMOVED	warning		Type 'RootCause' exists in the primary RSL but not in the copy.
RSL_COPY_TYPE_REMOVED	warning		Type 'SafetyMeasure' exists in the primary RSL but not in the copy.

Compared RSL copy: config_management

ID	Severity	Field / option	Message
RSL_COPY_FIELD_ADDED	warning	fulfilledBy	Field 'fulfilledBy' exists on CompReq in the copy but not in the primary RSL.
RSL_COPY_FIELD_ADDED	warning	guideword	Field 'guideword' exists on FailureMode in the copy but not in the primary RSL.
RSL_COPY_FIELD_ADDED	warning	potentialcause	Field 'potentialcause' exists on FailureMode in the copy but not in the primary RSL.
RSL_COPY_FIELD_CHANGED	warning		Parent of 'AoU' changed from 'RequirementSafety' to 'ControlMeasure'.
RSL_COPY_FIELD_CHANGED	warning	derived_from	Type of CompReq.derived_from changed from 'CompReqSourceId[1..]' to 'FeatReqId[1..]'.
RSL_COPY_FIELD_CHANGED	warning	description	Type of Requirement.description changed from 'Markup_String' to 'String'.
RSL_COPY_FIELD_REMOVED	warning	root_causes	Field 'root_causes' exists on AoU in the primary RSL but not in the copy.
RSL_COPY_FIELD_REMOVED	warning	guidewords	Field 'guidewords' exists on FailureMode in the primary RSL but not in the copy.
RSL_COPY_TYPE_ADDED	warning		Type 'ControlMeasure' exists in the copy but not in the primary RSL.
RSL_COPY_TYPE_ADDED	warning		Type 'StdReq' exists in the copy but not in the primary RSL.
RSL_COPY_TYPE_REMOVED	warning		Type 'Mitigation' exists in the primary RSL but not in the copy.
RSL_COPY_TYPE_REMOVED	warning		Type 'RootCause' exists in the primary RSL but not in the copy.
RSL_COPY_TYPE_REMOVED	warning		Type 'SafetyMeasure' exists in the primary RSL but not in the copy.

[anmittag]

Participants

@AlexanderLanin
@PhilippM-qorix
@a-zw
@masc2023
@RolandJentschETAS
@antonkri
@FScholPer
@MaximilianSoerenPollak
@PandaeDo
@dcalavrezo-qorix
@PhilipPartsch
@ubmarco

[anmittag]

Minutes

1 Docs-As-Code

• docs as code covers the metamodel

• there is no direct coupling of docs as code and the build system as it needs bazel-outputs to collect the required data
• the direct connection to source code is conceptional not available as it is based on "rsts", but meanwhile tool-extension offers this functionality

=> we are planning to close this gaps with some bazel-items similar to TLRC/LOBSTER-Dependable Elements

ToDo: Adapt the Requirements eclipse-score/infrastructure#69

• The connection of build elements with docs elements is necessary
• A single source of truth shall be used (like dependable element or umbrella target)
• It has to be ensured that build and doc elements are matching
• Lean Variant Handling has to be supported (feature enabling/disabling) kconfig
• IDE shall be supported, e.g. to identify all impacted artefacts
• A mechanism to invalidate dependent parts shall be supported e.g. detailed design changed => code is automated set to invalid
• Rule sets have to be established and checked, like e.g. location of requirements
• NiceToHave: Support of different views for several use cases (e.g. Security Architect, Developer, Safety Architect, ...)
• Backward API compatibility checks shall be supported

2 TLRC/LOBSTER-Dependable Elements

• TLRC: Description Language for different Elements, LOBSTER: json-file management tool, "BMW Dependable Element": connection between build and doc elements
• is not fitting to the current S-CORE Metamodel see https://github.com/orgs/eclipse-score/discussions/3311?sort=new#discussioncomment-18793558
• there is no converter available and several activities failed Rollout of Safety Sentinel communication#545 (comment)
• but all defined work-products have to be provided
• reference-integration build and the resulting elements/work products are missing => see Safety Aspects below

ToDo: Provide current Requirements @antonkri

3 Heterogenous Solution for S-CORE Release 1.0

• with minimum effort achieving maximum results
  • including HTML
  • how to ensure traceability?
  • feat(scripts_bazel): needs.json -> LOBSTER lobster-req-trace converter docs-as-code#654

4 Safety Aspects

• Currently we are following/depending on the S-CORE Process and the Metamodel
• TLRC/LOBSTER-Dependable Elements are not matching

5 Midterm Solution

• There is only ONE single meta-model including necessary work-products binding for all
• There is only ONE process description binding for all