docs: improve rep process reqs for tooling

Ref: closes #28

Author: aschemmel-tech

process/process_areas/requirements_engineering/guidance/requirements_guideline.rst

@@ -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
@@ -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")
 
 Checks
 ------

process/process_areas/requirements_engineering/guidance/requirements_process_reqs.rst

@@ -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
+      * Tool requirement
 
 .. _process_requirement_attributes:
 
@@ -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
@@ -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
@@ -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:
 
       * Yes
       * No
@@ -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:
 
       * QM
       * ASIL_B
@@ -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:
 
@@ -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
@@ -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"
+
 .. gd_req:: Requirements mandatory attributes provided
    :id: gd_req__req__attr_mandatory
    :status: valid
@@ -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
@@ -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`
 
@@ -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

process/process_areas/requirements_engineering/guidance/requirements_templates.rst

@@ -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
@@ -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
@@ -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
@@ -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
@@ -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

process/process_areas/requirements_engineering/requirements_concept.rst

@@ -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