diff --git a/process/general_concepts/score_review_concept.rst b/process/general_concepts/score_review_concept.rst index 54d4992c62..f0b523a6d5 100644 --- a/process/general_concepts/score_review_concept.rst +++ b/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,10 +90,10 @@ 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. @@ -101,7 +101,7 @@ 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 ^^^^^^^^^^^^^^^^^^^^ diff --git a/process/process_areas/architecture_design/guidance/architecture_process_reqs.rst b/process/process_areas/architecture_design/guidance/architecture_process_reqs.rst index b7a1cfcb03..baccf978c2 100644 --- a/process/process_areas/architecture_design/guidance/architecture_process_reqs.rst +++ b/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 diff --git a/process/process_areas/documentation_management/documentation_concept.rst b/process/process_areas/documentation_management/documentation_concept.rst index a2197ab88c..8a7d9666f3 100644 --- a/process/process_areas/documentation_management/documentation_concept.rst +++ b/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. diff --git a/process/process_areas/documentation_management/guidance/documentation_process_reqs.rst b/process/process_areas/documentation_management/guidance/documentation_process_reqs.rst index a1fb54bd83..0ea9f82cb8 100644 --- a/process/process_areas/documentation_management/guidance/documentation_process_reqs.rst +++ b/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 diff --git a/process/process_areas/documentation_management/guidance/documentation_templates.rst b/process/process_areas/documentation_management/guidance/documentation_templates.rst new file mode 100644 index 0000000000..9360fc8f8b --- /dev/null +++ b/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:: + | :id: doc__ + | :status: + | :security: + | :safety: + | :realizes: wp__ diff --git a/process/process_areas/documentation_management/guidance/index.rst b/process/process_areas/documentation_management/guidance/index.rst index 990ab606ed..7dd4c263e9 100644 --- a/process/process_areas/documentation_management/guidance/index.rst +++ b/process/process_areas/documentation_management/guidance/index.rst @@ -20,4 +20,5 @@ Guidance documentation_guideline documentation_checklist + documentation_templates documentation_process_reqs diff --git a/process/process_areas/platform_management/platform_management_workflow.rst b/process/process_areas/platform_management/platform_management_workflow.rst index cfac4504aa..02f8e60f9f 100644 --- a/process/process_areas/platform_management/platform_management_workflow.rst +++ b/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 diff --git a/process/process_areas/requirements_engineering/guidance/requirements_process_reqs.rst b/process/process_areas/requirements_engineering/guidance/requirements_process_reqs.rst index 179d26e574..6b986459f9 100644 --- a/process/process_areas/requirements_engineering/guidance/requirements_process_reqs.rst +++ b/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