fix implementation review findings by RolandJentschETAS · Pull Request #717 · eclipse-score/process_description

RolandJentschETAS · 2026-06-18T13:50:08Z

This pull request makes significant updates to the implementation process requirements and guidance documentation. The main focus is on clarifying the optional nature of detailed design documentation, simplifying and strengthening requirements for diagram and unit/interface attributes, and emphasizing consistency and traceability between documentation and source code. Several redundant or overly prescriptive requirements have been removed, and naming conventions are now highlighted as central for traceability.

Key changes include:

General Requirements and Documentation:

Clarified that detailed design description files and diagrams are optional, but if provided, must follow specific consistency and traceability rules.
Updated guidance to stress that naming in diagrams and descriptions must match source code to ensure traceability and prevent outdated or inconsistent documentation. [1] [2]

Diagram and Attribute Requirements:

Simplified diagram requirements: diagrams now require a unique name (not ID) and a description, with previous mandatory attributes (security, safety, status) and linkage requirements removed. [1] [2] [3]
Diagram consistency checks now focus on alignment with source code and design principles, rather than checking for a fixed set of mandatory attributes.

Unit and Interface Requirements:

Replaced unique ID requirements for units and interfaces with a focus on proper, descriptive naming that follows a project-wide convention for traceability.
Unit and interface descriptions are now required in the source code, with guidance on what the documentation should cover and the importance of keeping it up to date.

Work Product and Editorial Updates:

Minor editorial improvements for clarity and consistency in the implementation work products documentation. [1] [2] [3]

These changes streamline the documentation process, reduce unnecessary overhead, and ensure that all design artifacts remain consistent with the evolving codebase.

References:
[1] [2] [3] [4] [5] [6] [7] [8]

github-actions · 2026-06-18T13:53:23Z

The created documentation from the pull request is available at: docu-html

PandaeDo · 2026-06-19T07:42:20Z

              std_req__aspice_40__SWE-3-BP2[version==1]

-   Each diagram shall have a unique ID. It shall consist of three parts:
+   Each diagram shall have a unique name. It shall consist of three parts:


Suggested change

Each diagram shall have a unique name. It shall consist of three parts:

Each diagram shall have a unique ID. It shall consist of three parts:

We also named it unique ID in the other requirements like https://eclipse-score.github.io/process_description/pr-717/process_areas/architecture_design/guidance/architecture_process_reqs.html hat are using names. To the aspect to have it similar I would recommend to change it back.

Yes, but thats an different case. In the architecture, we have this all as Sphinx Objects. Here it is simply a plant UML file without any ID. We could only say, that path + filename build the ID.

PandaeDo · 2026-06-19T07:47:24Z


   This means for example that the word "shall" is not allowed in the title for all diagram.

-.. gd_req:: Diagram attribute: security


Whey the attributes are deleted? I guess we should keep them if a diagram is used.

As described above. Units are within a component and inherits all properties from it. Therefore it makes no sense (independently that it would be unclear how to do) to add security and safety to a plantuml / drawio inside the detail design.

PandaeDo · 2026-06-19T07:51:19Z

-      :colwidths: 30
+   It shall be checked if all diagrams are consistent with the source code and the design principles
+   outlined in the development plan. This includes checking that the naming of the units, their
+   interfaces and functions in any diagrams or descriptions matches the naming in the source code to ensure traceability.


We may could check this automated. MarCom is working on it. Could be useful as an outlook. We can connect with @hoe-jo for that

If this would be working it will be fine. Could set it as prio_3_automation ?

PandaeDo · 2026-06-19T07:51:58Z


-.. gd_req:: Unit attribute: UID
-   :id: gd_req__impl_unit_uid
+.. gd_req:: Unit naming


Suggested change

.. gd_req:: Unit naming

.. gd_req:: Unit attribute: UID

PandaeDo · 2026-06-19T07:52:55Z

   :complies: std_req__iso26262__software_843[version==1], std_req__aspice_40__SWE-3-BP1[version==1]

-   Each unit shall have a unique ID. It shall consist of three parts:
+   Each unit shall have a proper naming, which is unique within the component and


Please also consider text and following text against comment regarding UID / naming

Units have no spinx representation. Therefore it is unclear what a UID shall be.

PandaeDo · 2026-06-19T07:54:00Z

-   Consider the project's naming convention.
-
-.. gd_req:: Unit attribute: description
+.. gd_req:: Unit description


Suggested change

.. gd_req:: Unit description

.. gd_req:: Unit attribute: description

PandaeDo · 2026-06-19T07:55:14Z

   :satisfies: wf__sw_detailed_design[version==1]

-   Each unit shall be automatically linked (inverse direction) to the corresponding component id via the "belongs by" linkage.
+   Each unit shall have a description in the source code.


Maybe we should have to sections of process requirements. If they are selected and when we use automations and if not.

Automation is normally with tags

PandaeDo · 2026-06-19T07:57:52Z

+The unit design shall achieve quality attributes (like simplicity, modularity, and encapsulation)
+which shall be enforced through coding guidelines and static analysis tooling appropriate
+for the programming language in use (e.g. MISRA C for C/C++, Clippy lints for Rust) as specified
+in the project development plan to fulfill the guidelines :need:`ISO 26262-6 §8.4.5, Table 6 <std_req__iso26262__software_845>` and :need:`ASPICE SWE.3/SWE.4<std_req__aspice_40__SWE-3-BP3>` requirements.


We should describe guidelines in the guidelines and not refer to standards. These are not guidelines these are requirements and best practices.

PandaeDo · 2026-06-19T07:58:06Z


-The **source code** itself shall be self-documenting with meaningful naming and structure.
+The **source code** itself shall be self-documenting with meaningful naming and structure
+to fulfill the guidelines :need:`ISO 26262-6 §8.4.3 <std_req__iso26262__software_845>`.


fix implementation review findngs

2200794

RolandJentschETAS requested review from PandaeDo, aschemmel-tech, masc2023 and pahmann as code owners June 18, 2026 13:50

RolandJentschETAS changed the title ~~fix implementation review findngs~~ fix implementation review findings Jun 19, 2026

PandaeDo requested changes Jun 19, 2026

View reviewed changes

PandaeDo requested a review from hoe-jo June 19, 2026 07:58

	Each diagram shall have a unique name. It shall consist of three parts:
	Each diagram shall have a unique ID. It shall consist of three parts:


		This means for example that the word "shall" is not allowed in the title for all diagram.

		.. gd_req:: Diagram attribute: security

	.. gd_req:: Unit description
	.. gd_req:: Unit attribute: description

Conversation

RolandJentschETAS commented Jun 18, 2026

Uh oh!

github-actions Bot commented Jun 18, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants