Skip to content

docs: improve req process reqs for tooling #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
masc2023 merged 2 commits into from
Jun 10, 2025
Merged

docs: improve req process reqs for tooling #32

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4a6ad4a
docs: improve rep process reqs for tooling
aschemmel-tech Jun 4, 2025
d1e4a3d
docs: improve req process reqs for tooling - fixes
aschemmel-tech Jun 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 11 additions & 6 deletions process/process_areas/requirements_engineering/guidance/requirements_guideline.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,26 +39,29 @@ Templates
- VS Code Snippet
* - Stakeholder Requirements
- :need:`[[title]] <gd_temp__req__stkh_req>`
- stkh_req_t
- ``stkh_req__``
* - Feature Requirements
- :need:`[[title]] <gd_temp__req__feat_req>`
- feat_req_t
- ``feat_req__``
* - Component Requirements
- :need:`[[title]] <gd_temp__req__comp_req>`
- comp_req_t
- ``comp_req__``
* - AoU Requirements
- :need:`[[title]] <gd_temp__req__aou_req>`
- aou_req_t
- ``aou_req__``
* - Process Requirements
- :need:`[[title]] <gd_temp__req__process_req>`
- gd_req_t
- ``gd_req__``
* - Tool Requirements
- :need:`[[title]] <gd_temp__req__tool_req>`
- ``tool_req__``

Additionally for the formulation of requirements following template is available: :need:`[[title]]<gd_temp__req__formulation>`

Attributes
----------

For all requirements following mandatory attributes need to be defined:
For all requirements following mandatory attributes are defined:

.. needtable:: Overview of mandatory requirement attributes
:tags: requirements_engineering
Expand All @@ -72,6 +75,8 @@ For all requirements following mandatory attributes need to be defined:
* ID: The naming convention for the ID is defined `here <REPLACE_doc__naming_conventions>`.
* Furthermore the requirements need to be versioned. Therefore a hash value of the requirement will to be calculated. The concept is described: :ref:`traceability concept for requirements`
* For the remaining attributes only predefined values can be used. A more detailed description can be found here: :ref:`attributes of the requirements`
* Note that "rationale" is only mandatory for Stakeholder Requirements ...
* and process requirements do not need security and safety because these can be derived from the standards they comply to (as well type attributes as these would all be "Non-functional")

Copy link
Contributor

@hoe-jo hoe-jo Jun 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On that thought: Do feature requirements also need the security attribute? Or is the security determined from the feature architecture. This would mean that only component requirements would contain the attribute security?

Checks
------
Expand Down
61 changes: 42 additions & 19 deletions ...s/process_areas/requirements_engineering/guidance/requirements_process_reqs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,15 +24,18 @@ Process Requirements
:satisfies: wf__req__stkh_req, wf__req__feat_req, wf__req__comp_req
:complies: std_req__iso26262__support_6431, std_req__iso26262__support_6432

Requirements shall be hierarchically grouped into different levels.
Requirements shall be hierarchically grouped into three levels.

Following levels are defined:

* Stakeholder requirement
* Feature requirement
* Component requirement

Additionally there shall be the following logical groups of requirements:
* Assumption of use requirement
* Process requirement
Copy link
Member

@AlexanderLanin AlexanderLanin Jun 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"gd_req" is a process requirement? What about e.g. "wf__req"? Is "process requirement" an undefined group here?

Copy link
Contributor Author

@aschemmel-tech aschemmel-tech Jun 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wf__req should be a workflow of the requirements process, not a requirement. Process requirement = gd_req - Let's not mention standard requirements here as those are treated differently and I would say these are described in our process metamodel.

* Tool requirement

.. _process_requirement_attributes:

Expand All @@ -46,13 +49,13 @@ Process Requirement Attributes
:satisfies: wf__req__stkh_req, wf__req__feat_req, wf__req__comp_req
:complies: std_req__iso26262__support_6425, std_req__iso26262__support_6432

Each requirement shall have a unique ID. It shall be in a format which is also human readable and consists of
Each requirement shall have a unique ID. It shall consist of three parts:

* type of requirement
* last part of the feature tree
* keyword describing the content of the requirement.

The naming convention is defined here: `REPLACE_doc__naming_conventions`
Consider the project's naming convention.

.. gd_req:: Requirement attribute: title
:id: gd_req__requirements_attr_title
Expand All @@ -61,11 +64,9 @@ Process Requirement Attributes
:satisfies: wf__req__stkh_req, wf__req__feat_req, wf__req__comp_req
:complies: std_req__iso26262__support_6424

The title of the requirement shall provide a short summary of the description. This means that e.g. the word "shall" must not be used int the title for:
The title of the requirement shall provide a short summary of the description, but is not an "additional" requirement.

* Stakeholder Requirements
* Feature Requirements
* Component Requirements
This means that the word "shall" must not be used in the title for all requirements.

.. gd_req:: Requirement attribute: description
:id: gd_req__requirements_attr_description
Expand Down Expand Up @@ -102,7 +103,7 @@ Process Requirement Attributes
:tags: attribute, mandatory
:satisfies: wf__req__feat_req, wf__req__comp_req

Each requirement shall have a security relevance identifier:
Each requirement (apart from proccess req) shall have a security relevance identifier:
Copy link
Contributor

@hoe-jo hoe-jo Jun 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As mentioned above: do stakeholder and feature requirements also need the security attribute?

Copy link
Contributor

@masc2023 masc2023 Jun 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes, why do you think, there is a difference from safety attribute?


* Yes
* No
Expand All @@ -114,7 +115,7 @@ Process Requirement Attributes
:complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425
:satisfies: wf__req__stkh_req, wf__req__feat_req, wf__req__comp_req

Each requirement shall have a automotive safety integrity level (ASIL) identifier:
Each requirement (apart from proccess req) shall have a automotive safety integrity level (ASIL) identifier:
Copy link
Contributor

@hoe-jo hoe-jo Jun 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tool requirements?


* QM
* ASIL_B
Expand All @@ -138,7 +139,8 @@ Process Requirement Attributes
:tags: attribute, mandatory
:satisfies: wf__req__stkh_req

Each stakeholder requirement shall provide a in the attribute rationale the reason why that the requirement is needed.
Each stakeholder requirement shall provide an attribute rationale.
The rationale shall contain the reason why the requirement is needed.

.. _process_requirement_linkage:

Expand All @@ -154,9 +156,19 @@ Process Requirement Linkage

Requirements shall be linked to its adjacent level via the attribute satisfies.

* stakeholder requirements <-> feature requirements
* feature requirements <-> component requirements
* workflow <-> process requirements
* stakeholder requirements <- feature requirements
* feature requirements <- component requirements
* workflow <- process requirements
* process requirements <- tool requirements

.. gd_req:: Requirement Traceability
:id: gd_req__req__traceability
:status: valid
:tags: attribute, automated
:complies: std_req__iso26262__support_6432
:satisfies: wf__req__stkh_req, wf__req__feat_req, wf__req__comp_req

Bi-directional traceability shall be provided by adding a "back-link" via attribute satisfied by.

.. gd_req:: Requirement attribute: requirement covered
:id: gd_req__req__attr_req_cov
Expand Down Expand Up @@ -200,21 +212,29 @@ Process Requirement Linkage
* No

.. gd_req:: Requirement attribute: versioning
:id: gd_req__req__attr_hash
:id: gd_req__req__attr_version
:status: valid
:tags: attribute, automated
:satisfies: wf__req__stkh_req, wf__req__feat_req, wf__req__comp_req
:complies: std_req__iso26262__support_6425, std_req__iso26262__support_6434

It shall be possible to provide a versioning for requirements. It shall be possible to detect if any of the mandatory attributes differ from the versioning: :need:`gd_req__req__attr_mandatory`

A more detailed description of the concept can be found here: :need:`gd_req__req__attr_hash`
It shall be possible to provide a versioning for requirements. For this all mandatory attributes shall be taken into account: :need:`gd_req__req__attr_mandatory`

.. _process_requirement_checks:

Process Requirements Checks
'''''''''''''''''''''''''''

.. gd_req:: Requirement check: suspicious
:id: gd_req__req__attr_suspicious
:status: valid
:tags: attribute, automated
:satisfies: wf__req__stkh_req, wf__req__feat_req, wf__req__comp_req
:complies: std_req__iso26262__support_6425, std_req__iso26262__support_6434

Based on the requirement versioning it shall be checked if a parent requirement was updated but not the linked child requirements.
In case an update was detected, the attribute requirement covered shall be set to "No"
Comment on lines +235 to +236
Copy link
Contributor

@MaximilianSoerenPollak MaximilianSoerenPollak Jun 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for clarifying this. 'Requirement covered' still is a bit weird sounding for this explanation but I think this makes it clear for us what to do. 👍

Copy link
Member

@AlexanderLanin AlexanderLanin Jun 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not quite clear on the concept, as this sounds like we need to change the "requirement covered" automatically (and instantly) by modifying the rst files. But this is so far into the future, we don't need to clarify right now.


.. gd_req:: Requirements mandatory attributes provided
:id: gd_req__req__attr_mandatory
:status: valid
Expand All @@ -240,6 +260,9 @@ Process Requirements Checks
* Stakeholder Requirements
* Feature Requirements
* Component Requirements
* Tool Requirements

List of these weak words: just, about, really, some, thing, absolutely (to be extended)


.. gd_req:: Requirements linkage level
Expand All @@ -249,7 +272,7 @@ Process Requirements Checks
:complies: std_req__iso26262__support_6432
:satisfies: wf__req__stkh_req, wf__req__feat_req, wf__req__comp_req

Every feature- and component requirement shall be linked to at least one parent requirement according to the defined traceability scheme:
Every feature- and component requirement shall be linked to at least one valid parent requirement according to the defined traceability scheme:

:ref:`traceability concept for requirements`

Expand All @@ -260,7 +283,7 @@ Process Requirements Checks
:complies: std_req__iso26262__support_6423
:satisfies: wf__req__feat_req, wf__req__comp_req

It shall be checked if every feature- and component requirement is linked at least to one architectural element.
It shall be checked if every feature- and component requirement is linked at least to one valid architectural element on the same level.

.. gd_req:: Requirements linkage safety
:id: gd_req__req__linkage_safety
Expand Down
28 changes: 22 additions & 6 deletions process/process_areas/requirements_engineering/guidance/requirements_templates.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
Templates
=========

.. gd_temp:: Stakeholder Requirements Templates
.. gd_temp:: Stakeholder Requirements Template
:id: gd_temp__req__stkh_req
:status: valid
:complies: std_wp__iso26262__software_651, std_req__iso26262__support_641, std_req__iso26262__support_6421, std_req__iso26262__support_6425
Expand All @@ -27,11 +27,12 @@ Templates
.. stkh_req:: <Title>
:id: stkh_req__<Title>
:reqtype: <Functional|Interface|Process|Legal|Non-Functional>
:security: <YES|NO>
:safety: <QM|ASIL_B|ASIL_D>
:rational: <The rationale provides the reason that the requirement is needed.>
:status: <valid|invalid>

.. gd_temp:: Feature Requirements Templates
.. gd_temp:: Feature Requirements Template
:id: gd_temp__req__feat_req
:status: valid
:complies: std_wp__iso26262__software_651, std_req__iso26262__support_641, std_req__iso26262__support_6421, std_req__iso26262__support_6425
Expand All @@ -46,7 +47,7 @@ Templates
:satisfies: <link to stakeholder requirement id>
:status: <valid|invalid>

.. gd_temp:: Component Requirements Templates
.. gd_temp:: Component Requirements Template
:id: gd_temp__req__comp_req
:status: valid
:complies: std_wp__iso26262__software_651, std_req__iso26262__support_641, std_req__iso26262__support_6421, std_req__iso26262__support_6425
Expand All @@ -61,7 +62,7 @@ Templates
:satisfies: <link to feature requirement id>
:status: <valid|invalid>

.. gd_temp:: AoU Requirement Templates
.. gd_temp:: AoU Requirement Template
:id: gd_temp__req__aou_req
:status: valid
:complies: std_wp__iso26262__software_651, std_req__iso26262__support_641, std_req__iso26262__support_6421, std_req__iso26262__support_6425
Expand All @@ -76,19 +77,34 @@ Templates
:status: <valid|invalid>
:mitigates: <link to safety analysis>

.. gd_temp:: Process Requirements Templates
.. gd_temp:: Process Requirements Template
:id: gd_temp__req__process_req
:status: valid
:complies: std_wp__iso26262__software_651, std_req__iso26262__support_641, std_req__iso26262__support_6421, std_req__iso26262__support_6425

.. code-block:: rst

.. gd_req:: <Title>
:id: gd_req__<Tool>__<Title>
:id: gd_req__<process>__<Title>
:satisfies: <link to guidance id>
:complies: <link to standard requirement>
:status: <valid|invalid>

.. gd_temp:: Tool Requirements Template
:id: gd_temp__req__tool_req
:status: valid
:complies: std_wp__iso26262__software_651, std_req__iso26262__support_641, std_req__iso26262__support_6421, std_req__iso26262__support_6425

.. code-block:: rst

.. tool_req:: <Title>
:id: tool_req__<tool>__<Title>
:reqtype: Non-Functional
:security: <YES|NO>
:safety: <QM|ASIL_B|ASIL_D>
:satisfies: <link to process req id>
:status: <valid|invalid>

.. gd_temp:: Requirement Formulation Template
:id: gd_temp__req__formulation
:status: valid
Expand Down
2 changes: 1 addition & 1 deletion process/process_areas/requirements_engineering/requirements_concept.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,7 @@ Following attributes need to be filled manually for each requirement:
- This attribute contains a hash value which is calculated over all mandatory requirement attributes. However this script needs to be executed manually, as this information is required to be present in the rst file.
- Script / Bazel Target
* - Satisfies Hash
- It contains the hash of the parent requirement. If the parent requirement is changed the hash will also change and the linkage has to be revisited again. A more detailed description is provided here: :need:`gd_req__req__attr_hash`
- It contains the hash of the parent requirement. If the parent requirement is changed the hash will also change and the linkage has to be revisited again. A more detailed description is provided here: :need:`gd_req__req__attr_version`
- Script / Bazel Target
* - Implemented by
- During Build the code files are parsed for a defined tag which includes the requirement id. If this is located a link to the code will be added in the requirement
Expand Down