diff --git a/docs/design_decisions/DR-001-proc.rst b/docs/design_decisions/DR-001-proc.rst new file mode 100644 index 00000000000..bd069ee3621 --- /dev/null +++ b/docs/design_decisions/DR-001-proc.rst @@ -0,0 +1,277 @@ +.. + # ******************************************************************************* + # Copyright (c) 2025 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 + # ******************************************************************************* + +.. _decision_record_feature_as_independent_delivery: + +DR-001-Proc: Feature as Independent Delivery Product +======================================================= + +.. dec_rec:: Feature as Independent Delivery Product + :id: dec_rec__platform__feature_delivery + :status: accepted + :Context: Feature artifacts are bound to the S-CORE platform repository and cannot be delivered independently of the platform release. The previous idea of moving all artifacts into the SW-Module repository leads to cyclic dependencies. + :Decision: Feature artifacts are split: feature requirements and platform architecture remain in the S-CORE repository. Feature architecture and component artifacts are moved to the SW-Module repository (feature repository). The dependency direction is unambiguous: SW-Module repositories depend on the S-CORE repository, not the other way around. + + :Consequences: Process update required. Feature architecture and component artifacts are moved to SW-Module repositories. Feature requirements and logical feature interfaces remain in the S-CORE repository. The dependency rule is mandatory. + + +Context +------- + +The intent of this decision record is to resolve the cyclic dependency problem present in the +current solution and to make features more independent from the S-CORE platform. +The original idea was to move all feature artifacts into the SW-Module repositories that +also contain the feature code. This was intended to strengthen the following aspects: + +- Release independence +- Topic cohesion +- Reusability + +To validate the feasibility of this concept, an initial proof of concept (PoC) was built +in which all feature artifacts were moved into the SW-Module repository. +It turned out that this leads to cyclic dependencies. +In addition, during the development of the PoC it became clear that the current solution +already contains cyclic dependencies (see :ref:`fig-current-meta-model`). +Therefore, neither the current concept nor the original PoC approach is a viable solution. + +Decision +-------- + +The feature artifacts are split between the **S-CORE repository** and the +**SW-Module repositories** to avoid cyclic dependencies: + +- The S-CORE repository contains the stakeholder requirements and the platform architecture, + including the feature requirements (requirements at feature level). +- The SW-Module repository contains the feature architecture, the component requirements, + and the detailed design of the components. + +The dependency direction is unambiguous: SW-Module repositories depend on the S-CORE repository, +but not the other way around. The integration repository knows all repositories. +This rule structurally excludes cyclic dependencies (see :ref:`fig-new-meta-model`). + +Consequences +------------ + +- Process update to reflect the new artifact distribution +- Feature architecture and component artifacts are moved to the SW-Module repositories +- Feature requirements remain in the S-CORE repository +- Logical feature interfaces remain in the S-CORE repository +- The dependency rule "SW-Module repositories → S-CORE repository" is mandatory +- The integration repository takes the role of the only node with knowledge of all repositories + +New Solution (Alternative 3 – Split Artifacts) +----------------------------------------------- + +The new solution without cyclic dependencies is shown in :ref:`fig-new-meta-model`. +The new solution follows this approach: + +The **S-CORE repository** contains: + +1. The stakeholder requirements that the platform must fulfill + (black-box view of the platform). +2. The platform architecture that breaks the platform down into features, their + feature requirements (white-box view of the platform, black-box view of the features), + and their logical architecture interfaces. +3. The platform safety/security analysis and platform assumptions of use. + +A feature consists of components. A distinction is made between: + +- **Shared components** (e.g. BaseLibs): These are reused by multiple features + and reside in their own SW-Module repositories. A feature can reference such components + as a dependency. +- **Feature-specific components**: These are developed exclusively for the realization of a + specific feature and are probably not intended for reuse. + +The feature-specific components are bundled together with the feature artifacts in a single +SW-Module repository. This repository can therefore also be referred to as a **feature repository**. + +.. note:: + + A feature repository may also contain components witch are used from other features. + Unlike BaseLibs, these components are related to the feature and are not used by all S-CORE features. + A component that merely *implements* a Logical Architecture Interface *provided* by a feature is not considered shared; it remains specific to that feature. + +The **SW-Module repository (feature repository)** contains: + +1. The feature architecture that breaks the feature down into components, and their + component requirements (white-box view of the feature, black-box view of the component). +2. The component architecture and/or the detailed design of the feature-specific components + (white-box view of the component). +3. The feature safety/security analysis, component safety/security analysis, and module + assumptions of use. + +:ref:`fig-breakdown` illustrates exemplarily the decomposition from the platform via features +down to components, as well as the assignment of artifacts to the respective repositories. +The dependency relationships between repositories run exclusively from the SW-Module repository to the +S-CORE repository — never in the opposite direction. + +.. _fig-breakdown: + +.. figure:: _assets/DR-001-proc-breakdown.drawio.svg + :align: center + :width: 75% + + Breakdown of Artifacts + +A complete overview of all artifacts and their assignment to the repositories is shown in +:ref:`fig-new-meta-model`. + +**Building blocks meta model with new repository mapping (Alternative 3 – Split Artifacts)** + +.. _fig-new-meta-model: + +.. figure:: _assets/DR-001-proc-new_score_building_blocks_meta_model.drawio.svg + :align: center + :width: 75% + + Building blocks meta model with new repository mapping + +**Building blocks meta model with current repository mapping (status quo)** + +.. _fig-current-meta-model: + +.. figure:: _assets/DR-001-proc-current_score_building_blocks_meta_model.drawio.svg + :align: center + :width: 75% + + Building blocks meta model with current repository mapping (status quo) + + +Considered Alternatives +----------------------- + +Four alternatives were examined: + +**Alternative 1 – Status Quo (platform-centric feature management)** + All platform and feature artifacts are located in the S-CORE platform repository. + Component artifacts are in the SW-Module repository. Features can only be delivered with + the platform release. Cyclic dependencies already exist today. + → *not chosen* + +**Alternative 2 – Feature in the SW-Module repository** + Platform artifacts remain in the S-CORE repository; all feature artifacts (requirements, + architecture, tests) and the associated components move into the SW-Module repository. + Enables independent feature releases, but leads to cyclic dependencies, since the + SW-Module repository depends on the S-CORE repository and vice versa. + → *not chosen, due to cyclic dependencies* + +**Alternative 3 – Split artifacts (chosen solution)** + Feature requirements and platform architecture remain in the S-CORE repository. + Feature architecture and component artifacts move to the SW-Module repository. + The dependency direction is unambiguous: SW-Module repositories → S-CORE repository. + Cyclic dependencies are structurally excluded. + → **chosen** + +**Alternative 4 – Dedicated feature repository** + A separate feature repository sits between the S-CORE repository and the SW-Module repositories. + Addresses the use case where two implementations exist for the same feature and + copies of feature artifacts are to be avoided. + Increases complexity, the number of repositories, and maintenance effort. + → *not chosen* + + +Proof of Concept (PoC): Logging +-------------------------------- + +The **logging feature** was used as the PoC. The version shown here already implements +the chosen solution (Alternative 3). + +The feature black-box view (feature requirements) is defined in the ``score`` repository. +The feature architecture and the feature-specific component artifacts are located in the +``logging`` SW-Module repository. The logging feature additionally depends on the +``baselib`` repository and the ``baselib_rust`` repository, which are used as shared +components by multiple features. +The dependency direction runs exclusively from the ``logging`` SW-Module repository +to the ``score`` repository — never the other way around. + +.. figure:: _assets/DR-001-proc-PoC_logging.drawio.svg + :align: center + :width: 75% + + Proof of Concept: Logging Feature + +Glossary +-------- + +.. glossary:: + + Artifact + Any document or result produced during the development process, e.g. requirements, + architecture descriptions, tests or source code. + + Black-box view + Observation of a unit from the outside — only interfaces and behavior are visible, + not the internal structure. + + Decision Record (DR) + A document that describes, justifies, and records the consequences of an architecture + or process decision. + + Feature + A distinct unit of functionality of the S-CORE platform, realized by a set of components. + + Feature architecture + The description of how a feature is broken down into components + (white-box view of the feature). + + Feature repository + Designation for a SW-Module repository that contains, in addition to the + feature-specific source code, all associated feature artifacts (feature architecture, + component requirements, detailed design). + + Feature requirements + Requirements at the feature level. They describe what a feature must do and are + derived from the stakeholder requirements. + + Integration repository + Repository that knows all other repositories and is responsible for integrating the + overall platform. + + Component architecture + The detailed structure of a component (white-box view of the component), also + referred to as detailed design. + + Component requirements + Requirements at the component level, derived from the feature architecture. + + Platform architecture + The decomposition of the S-CORE platform into features (white-box view of the platform). + + S-CORE repository + The central platform repository containing stakeholder requirements, platform + architecture, and feature requirements. + + SEooC (Safety Element out of Context) + A safety element that can be developed and delivered independently of a concrete + system context, to facilitate integration into various projects. + + Shared components + Components reused by multiple features (e.g. BaseLibs) that reside in their own + SW-Module repositories. Features reference them as dependencies. + + SW-Module repository (SW-Module repo) + Repository containing feature architecture, component requirements, detailed design, + and source code of a feature implementation. + + Stakeholder requirements + Requirements placed on the S-CORE platform as a whole from the outside + (black-box view of the platform). + + White-box view + Observation of a unit from the inside — the internal structure and decomposition + are visible. + + Cyclic dependency + A dependency relationship in which two or more units depend on each other mutually, + leading to irresolvable build or versioning conflicts. diff --git a/docs/design_decisions/_assets/DR-001-proc-PoC_logging.drawio.svg b/docs/design_decisions/_assets/DR-001-proc-PoC_logging.drawio.svg new file mode 100644 index 00000000000..5b0bd11f5cc --- /dev/null +++ b/docs/design_decisions/_assets/DR-001-proc-PoC_logging.drawio.svg @@ -0,0 +1,4 @@ + + + +

baselibs repo

baselibs repo
baselibs_rust repo

logging repo

logging repo

score repo

score repo
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/design_decisions/_assets/DR-001-proc-breakdown.drawio.svg b/docs/design_decisions/_assets/DR-001-proc-breakdown.drawio.svg new file mode 100644 index 00000000000..cde95ace03b --- /dev/null +++ b/docs/design_decisions/_assets/DR-001-proc-breakdown.drawio.svg @@ -0,0 +1,4 @@ + + + +
 SW Modul Repository
 SW Modul Repository
 S-Core Repository
 S-Core Repository
implements
implements
Detailed Design Comp_B_2
Detailed Design Comp_B_2
Platform Arc
Platform Arc
uses
uses
Feature A
Feature A
provides
provides
Feature B
Feature B
Platform
Platform
has
has
Stakeholder Requirements
Stakeholder Requirem...
breakdown
breakdown
belogs to
belogs to
Feature A Requirements
Feature A Requiremen...
belongs to
belongs to
Feature B Requirements
Feature B Requiremen...
refinment
refinment
logical Interface B
logical Interface B
Feature A Arc
Feature A Arc
uses
uses
Comp_A_1
Comp_A_1
consists of
consists of
Comp_A_2
Comp_A_2
belongs to
belongs to
Comp_A_1 Requirements
Comp_A_1 Requirements
belongs to
belongs to
satisfies
satisfies
Comp_A_2 Requirements
Comp_A_2 Requirements
Feature B Arc
Feature B Arc
implements
implements
Comp_B_1
Comp_B_1
consists of
consists of
Comp_B_2
Comp_B_2
belongs to
belongs to
Comp_B_1 Requirements
Comp_B_1 Requirements
belongs to
belongs to
satisfies
satisfies
Comp_B_2 Requirements
Comp_B_2 Requirements

Platform Design

Platform Design
Comp_B_1 Arc
Comp_B_1 Arc
Comp_B_1_1
Comp_B_1_1
consists of
consists of
Comp_B_1_2
Comp_B_1_2
belongs to
belongs to
Comp_B_2_1 Requirements
Comp_B_2_1 Requireme...
belongs to
belongs to
satisfies
satisfies
Comp_B_2_2 Requirements
Comp_B_2_2 Requireme...
Unit_B_2_1
Unit_B_2_1
consists of
consists of
Unit_B_2_1
Unit_B_2_1

Feature Design

Feature Design

Componet Design

Componet Design
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/design_decisions/_assets/DR-001-proc-current_score_building_blocks_meta_model.drawio.svg b/docs/design_decisions/_assets/DR-001-proc-current_score_building_blocks_meta_model.drawio.svg new file mode 100644 index 00000000000..77dc0d72b45 --- /dev/null +++ b/docs/design_decisions/_assets/DR-001-proc-current_score_building_blocks_meta_model.drawio.svg @@ -0,0 +1,4 @@ + + + +
SW Modul Repository
SW Modul Repository
S-Core Repository
S-Core Repository
1, *
1, *
belongs_to
belongs_to
includes
includes
Feature
Feature
uses
uses
Component
Component
Feature
Requirements
Feature...
fulfills
fulfills
includes
includes
belongs_to
belongs_to
Feature
Architecture
Feature...
satifies
satifies
Component
Requirements
Component...
1,*
1,*
belongs_to
belongs_to
consists of
consists of
includes
includes
Unit
Unit
1, *
1, *
belongs_to
belongs_to
Source Code
Source Code
Stakeholder
 Requirements
Stakeholder...
satifies
satifies
implements
implements
Platform
Platform
1, *
1, *
consists of
consists of
has
has
1, *
1, *
Objectives
Objectives
1
1
1, *
1, *
fulfills
fulfills
uses
uses
Component
Architecture
Component...
satifies
satifies

belongs_to
belongs_to
Detailed
Design
Detailed...
satifies
satifies
implements
implements
consists of
consists of
implements
implements
1
1
*
*
Dependable Element
Dependable Element
includes
includes
1,*
1,*
*
*
1, *
1, *
Feature Safety/
Security Analysis
Feature Safety/...
Assumption of use
Assumption of use
- own AoU
-other AoU
- own AoU...
Platform Integration 
Tests
Platform Integration...
Feature
Integration Tests
Feature...
verifies
verifies
violates
violates
mitigated_by
mitigated_by
verifies
verifies
Component
Integration Tests
Component...
Component Safety /
Security Analysis
Component Safety /...
violates
violates
mitigated_by
mitigated_by
mitigated_by
mitigated_by
mitigated_by
mitigated_by
verifies
verifies
Unit Test
Unit Test
verifies
verifies
verifies
verifies
1
1
1,*
1,*
mitigated_by
mitigated_by
Platform Safety/
Security Analysis
Platform Safety/...
mitigated_by
mitigated_by
violates
violates
fulfils
fulfils
Logical Arc. Interface
Logical Arc. Interface
Legend
Legend
UML
(sphinx needs)
UML...
implicit
implicit
mandatory
mandatory
optional
optional
includes
includes
belongs_to
belongs_to
Dependable Element
View
Dependable Element...
Tool generated
Target not specified
Tool gener...
Line Color
Line Color
Line Style
Line Style
implements
implements
1
1
1, *
1, *
*
*
1
1
fulfills - but not the feature's own AoU
fulfills - but not the feature's own AoU
fulfills - but not the component's own AoU
fulfills - but not the component's own AoU
verifies
verifies
verifies
verifies
Delivery Container
Delivery Container
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/design_decisions/_assets/DR-001-proc-new_score_building_blocks_meta_model.drawio.svg b/docs/design_decisions/_assets/DR-001-proc-new_score_building_blocks_meta_model.drawio.svg new file mode 100644 index 00000000000..ef19229c805 --- /dev/null +++ b/docs/design_decisions/_assets/DR-001-proc-new_score_building_blocks_meta_model.drawio.svg @@ -0,0 +1,4 @@ + + + +

reference_integration

repository
reference_integrationrepository
SW Modul repository
SW Modul repository
score repository
score repository
belongs_to
belongs_to
provides
provides
uses
uses
Feature
Feature
uses
uses
Component
Component
Delivery Container
Delivery Container
fulfills
fulfills
includes
includes
belongs_to
belongs_to
satifies
satifies
covers - but not the own AoU
covers - but not the own AoU
Component
Requirements
Component...
1,*
1,*
belongs_to
belongs_to
belongs to
belongs to
includes
includes
Unit
Unit
1, *
1, *
belongs_to
belongs_to
Source Code
Source Code
Stakeholder
 Requirements
Stakeholder...
satifies
satifies
implements
implements
has
has
1, *
1, *
has
has
Platform
Platform
1, *
1, *
consists of
consists of
Objectives
Objectives
has
has
1, *
1, *
1, *
1, *
fulfills
fulfills
uses
uses
1, *
1, *
Component
Architecture
Component...

belongs_to
belongs_to
Detailed
Design
Detailed...
satifies
satifies
implements
implements
consists of
consists of
implements
implements
1
1
*
*
Dependable Element
Dependable Element
includes
includes
1,*
1,*
violates
violates
mitigated_by
mitigated_by
mitigated_by
mitigated_by
Platform
Assumptions of use
Platform...
- own AoU
-other AoU
- own AoU...
verifies
verifies
mitigated_by
mitigated_by
Platform Integration 
Tests
Platform Integration...
verifies
verifies
verifies
verifies
Feature
Integration Tests
Feature...
verifies
verifies
verifies
verifies
Component
Integration Tests
Component...
violates
violates
mitigated_by
mitigated_by
Component Safety /
Security Analysis
Component Safety /...
mitigated_by
mitigated_by
verifies
verifies
Unit Test
Unit Test
1
1
1,*
1,*
verifies
verifies
mitigated_by
mitigated_by
mitigated_by
mitigated_by
Platform Safety/
Security Analysis
Platform Safety/...
violates
violates
fulfils
fulfils
Logical Arc. Interface
Logical Arc. Interface
Legend
Legend
UML
(sphinx needs)
UML...
implicit
implicit
mandatory
mandatory
optional
optional
includes
includes
belongs_to
belongs_to
Dependable Element
View
Dependable Element...
Tool generated
Target not specified
Tool gener...
Line Color
Line Color
Line Style
Line Style
implements
implements
1
1
1, *
1, *
*
*
1
1
fulfills - but not the feature's own AoU
fulfills - but not the feature's own AoU
fulfills - but not the component's own AoU
fulfills - but not the component's own AoU
verifies
verifies
verifies
verifies
includes
includes
Platform
Architecture
Platform...
Feature
Architecture
Feature...
Modul
Assumptions of use
Modul...
- own AoU
-other AoU
- own AoU...
satifies
satifies
Feature
Requirements
Feature...
Feature Safety/
Security Analysis
Feature Safety/...
covers - but not the own AoU
covers - but not the own AoU
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/design_decisions/_assets/DR-001-proc-platform_design.drawio.svg b/docs/design_decisions/_assets/DR-001-proc-platform_design.drawio.svg new file mode 100644 index 00000000000..d9ec27f92e5 --- /dev/null +++ b/docs/design_decisions/_assets/DR-001-proc-platform_design.drawio.svg @@ -0,0 +1,4 @@ + + + +
 S-Core Repository
 S-Core Repository

Platform Design

Platform Design
Platform Arc
Platform Arc
uses
uses
Feature A
Feature A
provides
provides
Feature B
Feature B
Platform
Platform
has
has
Stakeholder Requirements
Stakeholder Requirem...
breakdown
breakdown
belogs to
belogs to
Feature A Requirements
Feature A Requiremen...
belongs to
belongs to
Feature B Requirements
Feature B Requiremen...
refinment
refinment
logical Interface B
logical Interface B

Platform Design

Platform Design
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/design_decisions/index.rst b/docs/design_decisions/index.rst index 593cda3e448..05347eb85b1 100644 --- a/docs/design_decisions/index.rst +++ b/docs/design_decisions/index.rst @@ -24,3 +24,12 @@ Infrastructure :glob: DR-*-infra* + +Process +~~~~~~~ + +.. toctree:: + :maxdepth: 1 + :glob: + + DR-*-proc*