fix implementation review findings #717
+67
−242
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -15,6 +15,9 @@ | |||||
| Process Requirements | ||||||
| #################### | ||||||
|
|
||||||
| Please notice, that detail design description files (within MarkDown or RestructuredText) are optional. | ||||||
| Also diagrams are optional, but if they are created, they shall have the following attributes to ensure consistency and traceability. | ||||||
|
|
||||||
| .. gd_req:: Static Diagram for Unit Interactions | ||||||
| :id: gd_req__impl_static_diagram | ||||||
| :status: valid | ||||||
|
|
@@ -26,7 +29,7 @@ Process Requirements | |||||
| std_req__iso26262__software_845[version==1], | ||||||
| std_req__aspice_40__SWE-3-BP1[version==1] | ||||||
|
|
||||||
| The static diagram shall represent the units and their relationships using UML notations. | ||||||
|
|
||||||
| Diagram Attributes | ||||||
| ------------------ | ||||||
|
|
@@ -42,11 +45,11 @@ Diagram Attributes | |||||
| std_req__iso26262__software_845[version==1], | ||||||
| std_req__aspice_40__SWE-3-BP2[version==1] | ||||||
|
|
||||||
| Each diagram shall have a unique name. It shall consist of three parts: | ||||||
|
|
||||||
| * type of diagram | ||||||
| * structural element | ||||||
| * keyword describing the content of the diagram | ||||||
|
|
||||||
| Consider the project's naming convention. | ||||||
|
|
||||||
|
|
@@ -66,44 +69,6 @@ Diagram Attributes | |||||
|
|
||||||
| This means for example that the word "shall" is not allowed in the title for all diagram. | ||||||
|
|
||||||
|
Contributor
There was a problem hiding this comment. Whey the attributes are deleted? I guess we should keep them if a diagram is used.
Contributor
Author
There was a problem hiding this comment. 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. |
||||||
| .. gd_req:: Diagram attribute: description | ||||||
| :id: gd_req__impl_diagram_description | ||||||
| :status: valid | ||||||
|
|
@@ -112,241 +77,87 @@ Diagram Attributes | |||||
| :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] | ||||||
| :satisfies: wf__sw_detailed_design[version==1] | ||||||
|
|
||||||
| Each diagram shall have a description. | ||||||
|
|
||||||
| .. _detailed_design_linkage: | ||||||
|
|
||||||
| Diagram Checks | ||||||
| '''''''''''''' | ||||||
|
|
||||||
| .. gd_req:: Diagram mandatory consistency | ||||||
| :id: gd_req__impl_diagram_consistency | ||||||
| :status: valid | ||||||
| :version: 1 | ||||||
|
RolandJentschETAS marked this conversation as resolved.
|
||||||
| :tags: prio_2_manual, attribute, check | ||||||
| :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] | ||||||
| :satisfies: wf__sw_detailed_design[version==1] | ||||||
|
|
||||||
| 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. | ||||||
|
Contributor
There was a problem hiding this comment. 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
Contributor
Author
There was a problem hiding this comment. If this would be working it will be fine. Could set it as prio_3_automation ? |
||||||
| That means the diagrams and descriptions should not be outdated and be consistent with | ||||||
| the source code and not introduce new terminology or concepts that are not present in the code. | ||||||
|
|
||||||
| Unit Attributes | ||||||
| --------------- | ||||||
|
|
||||||
| .. gd_req:: Unit naming | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
Contributor
Author
There was a problem hiding this comment. See above |
||||||
| :id: gd_req__impl_unit_naming | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
Contributor
Author
There was a problem hiding this comment. See above |
||||||
| :status: valid | ||||||
| :version: 1 | ||||||
| :tags: manual_prio_1, attribute, mandatory | ||||||
| :satisfies: wf__sw_detailed_design[version==1] | ||||||
| :complies: std_req__iso26262__software_843[version==1], std_req__aspice_40__SWE-3-BP1[version==1] | ||||||
|
|
||||||
| Each unit shall have a proper naming, which is unique within the component and | ||||||
|
Contributor
There was a problem hiding this comment. Please also consider text and following text against comment regarding UID / naming
Contributor
Author
There was a problem hiding this comment. Units have no spinx representation. Therefore it is unclear what a UID shall be. |
||||||
| follows a consistent naming convention. The name should be descriptive and reflect | ||||||
| the functionality of the unit to ensure traceability and understandability. | ||||||
|
|
||||||
| The naming convention should be defined in the project guidelines and consistently applied across all units. | ||||||
|
|
||||||
| .. gd_req:: Unit description | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
Contributor
Author
There was a problem hiding this comment. See above |
||||||
| :id: gd_req__impl_unit_description | ||||||
| :status: valid | ||||||
| :version: 1 | ||||||
| :tags: manual_prio_1, mandatory | ||||||
| :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] | ||||||
| :satisfies: wf__sw_detailed_design[version==1] | ||||||
|
|
||||||
| Each unit shall have a description in the source code. | ||||||
|
Contributor
There was a problem hiding this comment. Maybe we should have to sections of process requirements. If they are selected and when we use automations and if not.
Contributor
Author
There was a problem hiding this comment. Automation is normally with tags |
||||||
|
|
||||||
| Interface Attributes | ||||||
| -------------------- | ||||||
|
|
||||||
| .. gd_req:: Interface naming | ||||||
| :id: gd_req__impl_interface_naming | ||||||
| :status: valid | ||||||
| :version: 1 | ||||||
| :tags: manual_prio_1, mandatory | ||||||
| :satisfies: wf__sw_detailed_design[version==1] | ||||||
| :complies: std_req__iso26262__software_843[version==1], std_req__aspice_40__SWE-3-BP1[version==1] | ||||||
|
|
||||||
| Each interface shall have a proper naming, which is unique within the component and | ||||||
| follows a consistent naming convention. The name should be descriptive and reflect | ||||||
| the functionality of the interface to ensure traceability and understandability. | ||||||
|
|
||||||
| Consider the project's naming convention. | ||||||
|
|
||||||
| .. gd_req:: Interface description | ||||||
| :id: gd_req__impl_interface_description | ||||||
| :status: valid | ||||||
| :version: 1 | ||||||
| :tags: manual_prio_1, mandatory | ||||||
| :complies: std_req__iso26262__support_6421[version==1], std_req__iso26262__support_6425[version==1] | ||||||
| :satisfies: wf__sw_detailed_design[version==1] | ||||||
|
|
||||||
| Each interface shall have a description in the source code if the source code does not | ||||||
| already provide sufficient information. It should provide a clear and comprehensive explanation | ||||||
| of the interface's purpose, its inputs and outputs, and how it interacts with other units | ||||||
| or components. The description should be sufficient to allow users of the interface | ||||||
| to understand how to interact with it without needing to read the implementation details. | ||||||
| It should also include any relevant information about the expected behavior, constraints, | ||||||
| and any assumptions made in the design of the interface. The documentation should be | ||||||
| maintained and updated as the implementation evolves to ensure it remains accurate and useful. | ||||||
|
|
||||||
| Dependency Analysis | ||||||
| ''''''''''''''''''' | ||||||
|
|
@@ -360,7 +171,8 @@ Dependency Analysis | |||||
| :complies: std_req__iso26262__software_942[version==1] | ||||||
|
|
||||||
| For each component a dependency tree view shall be created to support design inspection and Safety Analysis. | ||||||
| It shall show the libraries used by the component (i.e. which libraries are linked to the component, | ||||||
| defined as CI build tool target) up to the leaves of the tree. | ||||||
|
|
||||||
| .. needextend:: docname is not None and "process_areas/implementation" in docname | ||||||
| :+tags: implementation | ||||||
|
|
||||||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.