Merge pull request #44 from eclipse-score/fix_review_findings

fix review findings during tool requirements review

Author: masc2023

process/general_concepts/score_review_concept.rst

@@ -17,7 +17,7 @@
 Review and Inspection Concept
 =============================
 
-.. doc_concept:: Workproduct Inspections Concept
+.. doc_concept:: Work product Inspections Concept
    :id: doc_concept__wp_inspections
    :status: valid
 
@@ -79,8 +79,8 @@ The detailed design and coding inspection is not of this kind. Here we define th
 already has the (formal) character of an inspection, i.e. the review checklist is used.
 The scope of such a detailed design / code inspection is always the change introduced, as documented in github.
 The inspection is initiated by the author of the change and reviewers are invited automatically
-based on the CODEOWNER(s) definition of the modified files. In case the fixing of review findings is not agreed
-between reviewer(s) and author, the safety manager or quality manager can be added to the review to moderate a solution.
+based on an implemented technical reviewer mechanism defined for the modified files. In case the fixing of review findings is not agreed
+between reviewer(s) and author, the safety manager, security manager or quality manager can be added to the review to moderate a solution.
 
 The initial step for requirements and architecture is the (informal) GitHub review on every Pull-Request
 (resp. Change Request, see `REPLACE_doc__contr_guideline`)
@@ -90,18 +90,18 @@ In this review the checklist entries shall be considered which are tagged as "in
 
 The last step is initiated by the safety manager, security manager or quality manager:
 He asks the main work product author to set the work product's status to "valid(inspected)" and start a Pull-Request (PR).
-GitHub will automatically ask for a review by the defined one or more "CODEOWNER" of the work product.
+GitHub will automatically ask for a review by the defined one or more reviewer implemented by the technical reviewer mechanism of the work product.
 In the PR description the inspection result will be documented for each checklist item
 (pass/fail - with link to a ticket for the corrections, or by citing the checklist item in the github comment).
-The CODEOWNER(s)=reviewers will fill out the checklist and add their findings on the work product in the PR.
+The reviewers will fill out the checklist and add their findings on the work product in the PR.
 They close their review activity by documenting their verdict as "Approve" or "Request Changes".
 Any one "Request Changes" will block the PR from being merged. Note that the PR author cannot "Approve" or "Request Changes".
 After all requested reviews were done, the author answers the findings in GitHub comments and/or performs corrections of the work products.
 Then the reviewer(s) re-review and adapt their verdict accordingly.
 In case the author or the reviewer(s) cannot agree on a solution, the safety/security/quality manger
 who initiated the inspection will be asked to moderate this by requesting also his review.
 
-The following picture shall illustrate how a status lifecycle of a requirement workproduct will look like.
+The following picture shall illustrate how a status lifecycle of a requirement work product will look like.
 The lifecycle for an architecture work product should be similar.
 
 .. figure:: _assets/inspection_workflow.drawio.svg
@@ -115,7 +115,7 @@ The lifecycle for an architecture work product should be similar.
 #. (Informal) Pull-Request Review
 #. Merge valid requirement to main
 #. During development and verification steps the requirement is reworked and again put to PR Review
-#. Implementation and verification workproducts are linked
+#. Implementation and verification work products are linked
 #. Safety manager initiates a (formal) Pull-Request Inspection
 #. After finding resolution, the requirement is merged in valid(inspected) state
 #. In case of changes the requirement returns in the valid state
@@ -133,7 +133,7 @@ for those which are QM but are security related the security manger may request
 but also the quality manager may ask for inspection for critical QM work products.
 
 Judging if the maturity of a work product is already enough to request an inspection
-can be based for example for the requiremnts on their "Implemented by", "Verified by" and "Requirement Covered" attribute.
+can be based for example for the requirements on their "Implemented by", "Verified by" and "Requirement Covered" attribute.
 For example when requesting a new feature by filling out the :need:`gd_temp__change__feature_request`
 you are asked to also specify the feature's requirements
 - it is not expected that the maturity of the requirements is already enough at this time to make a good inspection.
@@ -147,8 +147,8 @@ Reviewers shall comment also the checklist items which they mark as passed, as a
 to be able to later explain what they considered during review
 (for example in case a requirement is found to be wrong after the release, to be able to do a lessons learned).
 
-Any workproduct which is subject to inspection and is modified after an inspection
-shall transition from "valid(inspected)" back to "valid" state. This shall be automaticly checked.
+Any work product which is subject to inspection and is modified after an inspection
+shall transition from "valid(inspected)" back to "valid" state. This shall be automatically checked.
 
 Process Requirements
 ^^^^^^^^^^^^^^^^^^^^

process/process_areas/architecture_design/guidance/architecture_process_reqs.rst

@@ -112,7 +112,7 @@ Attributes of Architectural Elements
    :status: valid
    :tags: attribute, mandatory
 
-   Each requirement shall have a security relevance identifier:
+   Each architectural element shall have a security relevance identifier:
 
       * Yes
       * No
@@ -123,7 +123,7 @@ Attributes of Architectural Elements
    :tags: attribute, mandatory
    :complies: std_req__iso26262__support_6421, std_req__iso26262__support_6425
 
-   Each requirement shall have a automotive safety integrity level (ASIL) identifier:
+   Each architectural element shall have a automotive safety integrity level (ASIL) identifier:
 
       * QM
       * ASIL_B
@@ -135,7 +135,7 @@ Attributes of Architectural Elements
    :tags: attribute, mandatory
    :complies: std_req__iso26262__support_6425
 
-   Each requirement shall have a status:
+   Each architectural element shall have a status:
 
       * valid
       * invalid

process/process_areas/documentation_management/documentation_concept.rst

@@ -25,7 +25,7 @@ and "Part 8: Supporting processes".
 
 Key concept
 ^^^^^^^^^^^
-The Documentation Management Plan should define the strategy to manage the identifed documentations
+The Documentation Management Plan should define the strategy to manage the identified documentations
 in an effective and repeatable way for the project life cycle.
 
 

process/process_areas/documentation_management/guidance/documentation_process_reqs.rst

@@ -17,6 +17,54 @@
 Document Management Process Requirements
 ========================================
 
+.. gd_req:: Document Types
+   :id: gd_req__doc_types
+   :status: valid
+   :complies: std_req__iso26262__support_1043
+
+   There is only one generic document type:
+   * document
+
+    .. note::
+      This type is the ONLY type, which can be used for realizing concrete work products,
+      e.g. Safety Plan
+
+   .. note::
+      Process documents are not generic documents and types for that shall only used for
+      process definition, as defined
+
+      * gd_chklst
+      * gd_guidl
+      * gd_req
+      * gd_temp
+      * doc_concept
+      * doc_getstrt
+      * workproduct
+      * workflow
+      * role
+
+
+.. gd_req:: Document attributes
+   :id: gd_req__doc_attributes
+   :status: valid
+   :complies: std_req__iso26262__support_1043
+
+   Documents shall have the following manual attributes:
+
+   * id
+   * status
+   * security
+   * safety
+   * realizes
+
+   Compare also  :need:`gd_temp__documentation`
+
+   Documents shall have automatic added attributes:
+
+   * author
+   * approver
+   * reviewer
+
 .. gd_req:: Document Author
    :id: gd_req__doc_author
    :status: valid
@@ -34,7 +82,7 @@ Document Management Process Requirements
    :complies: std_req__iso26262__support_1045
 
    Documents headers shall contain an "approver" attribute, which is added during documentation build
-   and contains the last PR CODEOWNER reviewer of the file containing the document.
+   and contains the name of the last approval reviewer of the file containing the document.
 
 .. gd_req:: Document Reviewer
    :id: gd_req__doc_reviewer

process/process_areas/documentation_management/guidance/documentation_templates.rst

@@ -0,0 +1,30 @@
+..
+   # *******************************************************************************
+   # 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
+   # *******************************************************************************
+
+.. _documentation_templates:
+
+Documentation Templates
+=======================
+
+.. gd_temp:: Documentation Template
+   :id: gd_temp__documentation
+   :status: valid
+   :complies: std_req__iso26262__support_1045
+
+   | .. document:: <Document Name>
+   |    :id: doc__<Document Name>
+   |    :status: <valid|invalid>
+   |    :security: <YES|NO>
+   |    :safety: <QM|ASIL_B|ASIL_D>
+   |    :realizes: wp__<name of wp in process description>

process/process_areas/documentation_management/guidance/index.rst

@@ -20,4 +20,5 @@ Guidance
 
    documentation_guideline
    documentation_checklist
+   documentation_templates
    documentation_process_reqs

process/process_areas/platform_management/platform_management_workflow.rst

@@ -26,7 +26,7 @@ Workflow Platform Management
    :supported_by: rl__safety_manager, rl__security_manager, rl__quality_manager
    :input: wp__policies, wp__issue_track_system
    :output: wp__platform_mgmt, wp__project_mgt, wp__document_mgt_plan
-   :contains: gd_temp__platform__mgmt_plan, gd_guidl__platform__mgmt_plan, gd_guidl__documentation, gd_chklst__documentation__review
+   :contains: gd_temp__platform__mgmt_plan, gd_guidl__platform__mgmt_plan, gd_guidl__documentation, gd_chklst__documentation__review, gd_temp__documentation
    :has: doc_concept__platform__process, doc_getstrt__platform__process
 
    The Platform Management Plan shall include the plans as defined by the

process/process_areas/requirements_engineering/guidance/requirements_process_reqs.rst

@@ -89,12 +89,11 @@ Process Requirement Attributes
    :tags: attribute, mandatory
    :satisfies: wf__req__stkh_req, wf__req__feat_req, wf__req__comp_req
 
-   Each requirement shall have a type of one of following options:
+   Each requirement, apart from process requirements, shall have a type of one of following options:
 
       * Functional
       * Interface
       * Process
-      * Legal
       * Non-Functional
 
 .. gd_req:: Requirements attribute: security
@@ -128,7 +127,7 @@ Process Requirement Attributes
    :complies: std_req__iso26262__support_6425
    :satisfies: wf__req__stkh_req, wf__req__feat_req, wf__req__comp_req
 
-   Each requirement shall have a status:
+   Each requirement, apart from process requirements, shall have a status:
 
       * valid
       * invalid