From 6e7f3100c2e916d5732057ee853e80bb3ebc41a2 Mon Sep 17 00:00:00 2001 From: "markus.schu" Date: Thu, 4 Sep 2025 18:39:19 +0200 Subject: [PATCH] update change management Fix audit findings, Align with Problem Resolution Define issue template for change request Remove links to score repo Resolves: #53 --- .github/ISSUE_TEMPLATE/3-change.yml | 94 ++++++ .../score_lifecycle_concept.rst | 2 +- .../change_management_concept.rst | 152 +++------- .../change_management_getstrt.rst | 32 +- .../change_management_roles.rst | 2 +- .../change_management_workflow.rst | 94 ++++-- .../change_management_workproducts.rst | 6 +- ...ge_management_decision_record_template.rst | 1 - .../guidance/change_management_guideline.rst | 273 ++++++++++++------ .../guidance/change_management_reqs.rst | 48 +-- 10 files changed, 461 insertions(+), 243 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/3-change.yml diff --git a/.github/ISSUE_TEMPLATE/3-change.yml b/.github/ISSUE_TEMPLATE/3-change.yml new file mode 100644 index 0000000000..7119196e01 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/3-change.yml @@ -0,0 +1,94 @@ +# ******************************************************************************* +# 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 +# ******************************************************************************* + +name: "Change Request" +description: Issue to track a change +title: "Change: Your Change Request title" +labels: ["codeowner_review"] +body: + - type: dropdown + attributes: + label: Change Request Type + options: + - Feature Request + - Feature Modification + - Component Request + - Component Modification + default: 0 + validations: + required: true + - type: textarea + attributes: + label: Description of the Change Request + description: | + - Exact description of the Change Request + - Impact to users of the feature/component + - Use following template within a PR and link it to this issue + [Change Management Feature Request Template](https://eclipse-score.github.io/process_description/main/process_areas/change_management/guidance/change_management_feature_template.html) needs to be used + [Change Management Component Request Template](https://eclipse-score.github.io/process_description/main/process_areas/change_management/guidance/change_management_component_template.html) needs to be used + [For (Process) Improvements, Improvement Issue Template](https://github.com/eclipse-score/process_description/blob/main/.github/ISSUE_TEMPLATE/2-improvement.yml) needs to be used + validations: + required: true + - type: textarea + attributes: + label: Estimates for realization + description: | + - Estimate the effort, resources, risk for the realization + validations: + required: true + - type: checkboxes + attributes: + label: Affects work products + options: + - label: Requirements + - label: Architecture + - label: Safety/Security Analysis + - label: Detailed Design + required: true + - type: textarea + attributes: + label: Impact analysis + description: | + - Details on the impacted work products + - Use the following template and/or run the impact analysis tool provided + If the following template is use within a PR, link it to this issue + [Change Management Impact Analysis Template](https://eclipse-score.github.io/process_description/main/process_areas/change_management/guidance/change_management_impact_analysis_template.html) needs to be used + validations: + required: true + - type: checkboxes + attributes: + label: Safety or Security relevance + options: + - label: none + - label: Safety relevant + - label: Security relevant + validations: + required: true + - type: dropdown + attributes: + label: ASIL classification + options: + - QM + - ASIL_B + default: 0 + validations: + required: true + - type: dropdown + attributes: + label: Expected Implementation Version + options: + - 0.5 + - 1.0 + default: 0 + validations: + required: false diff --git a/process/general_concepts/score_lifecycle_concept.rst b/process/general_concepts/score_lifecycle_concept.rst index b94f980059..f23551a166 100644 --- a/process/general_concepts/score_lifecycle_concept.rst +++ b/process/general_concepts/score_lifecycle_concept.rst @@ -21,7 +21,7 @@ Contributions to the project are driven by feature/component requests. As features and components are the main structuring elements of the project, new features and components are requested by feature or components requests (compare -:need:`wf__change_cr_an_change_request`). Both are special types of change requests. +:need:`wf__change_create_cr`). Both are special types of change requests. The figure below shows the standard lifecycle of any feature/component in the project. diff --git a/process/process_areas/change_management/change_management_concept.rst b/process/process_areas/change_management/change_management_concept.rst index 3e20480311..f9dba55b99 100644 --- a/process/process_areas/change_management/change_management_concept.rst +++ b/process/process_areas/change_management/change_management_concept.rst @@ -26,18 +26,17 @@ including the requirements of the different stakeholders for the Change Manageme Key concept *********** -A Change Request is the **ONLY** way to contribute (compare `REPLACE_doc__contr_guideline`) -new features or to modify the scope of existing features in the **S-CORE** project. -As features are built-up by Components a Change Request is also needed to add new Components or -to modify the scope of existing Components. -As a Software Module is defined as the top-level Component, all statements here for Components -are also valid for Software Modules. +A Change Request is the **ONLY** way to contribute new features or to modify the scope +of existing features in the project. +As features are built-up by Components a Change Request is also needed to add new +Components or to modify the scope of existing Components. +As a Software Module is defined as the top-level Component, all statements here for +Components are also valid for Software Modules. Inputs ****** #. Stakeholders for the Change Requests? -#. Which Change Requests types can we derive from that? #. Which attributes are required? #. Which activities are required? @@ -46,15 +45,23 @@ Stakeholders for the Change Requests #. :need:`Contributor ` - * Contributes features and components to grow the **S-CORE** content - - Contribution include scope modification of existing features/components or adding new - features/components. + * In general contributes features and components to grow the project content + * Creates change requests, analyzes changes, implement changes #. :need:`Committer ` - * Verifies that the contribution fulfills the **S-CORE** policies - * Approves the contribution + * Verifies that the contribution including change requests fulfills the project policies + * Approves all change request activities besides changes closing + * Is responsible to initiate the the closure of the change request + +#. :need:`Technical Lead `, :need:`Module Lead ` + + * Supports all change request activities + * Approves the closing of the change request + +#. :need:`Safety Manager `, :need:`Security Manager `, :need:`Quality Manager ` + + * Supports all change request activities Standard Requirements ===================== @@ -65,89 +72,33 @@ Also requirements of standards need to be taken into consideration: * ASPICE * ISO SAE 21434 -Change Request Types -******************** - -Feature -======= - -This Change Request describes a potential new feature for the platform. -The Change Request uses the Feature request template: :ref:`chm_feature_templates`. - -Feature Modification -==================== - -This Change Request describes a scope modification of an existing feature (requirement or work -product). The Change Request modifies the already existing Feature Request template: :ref:`chm_feature_templates`. - -Component -========= - -This Change Request describes a potential new component for the platform. -The Change Request uses the Component request template: :ref:`chm_component_templates`. - -Component Modification -====================== - -This Change Request describes a scope modification of an existing component (requirement or work -product). The Change Request modifies the already existing Component Request template: :ref:`chm_component_templates`. - - .. _chm_attributes: Attributes of Change Requests ***************************** -The required attributes for the Change Requests are defined in this subchapter. - -Following attributes need to be filled manually for each Change Request: - -.. list-table:: Manual Attributes - :header-rows: 1 - :widths: 15,85 - - * - Attribute - - Description - * - Unique ID - - The unique id - * - Status - - The status of a Change Request can either be "draft", "in review", "accepted" or "rejected". - * - Title - - Reason for the Change Request - * - Description - - Exact description of the Change Request - * - Safety - - These attribute describes the impact on functional safety. - * - Security - - This attribute describes the impact on security - * - Change Request Type - - Following types are defined: [Feature, Feature Modification, Component, Component Modification] - * - Affected work products - - Links to the work products affected by the Change Request - * - Milestone - - Planned date (milestone) of deployment of the Change Request +The required attributes for the Change Request are defined here: :ref:`chm_process_change_request_attributes`. Activities for a Change Request ******************************* -.. _chm_analysis: +.. _chm_creation: -Analysis of the Change Request +Creation of the Change Request ============================== +Use the content :ref:`Feature Request Template ` or +:ref:`Component Request Template ` to create a Change Request. -The affected work products must be identified. -The potential impact on functional safety and security must be addressed. -Schedule, risks, resources for the realization must be evaluated. -Verification measures must be defined. -Use therefore the : :ref:`Impact Analysis Template `. +In case safety or security is affected, in addition the impact analysis template +: :ref:`Impact Analysis Template ` can be used to detail +out the impact on safety/security. -.. _chm_evaluation: - -Evaluation of the Change Request -================================ +.. _chm_analysis: -Based on the analysis results decision about the acceptance, rejection or delay must be taken +Analysis of the Change Request +============================== +Based on the analysis results decision about the acceptance or rejection must be taken by authorized persons. Authorized person includes @@ -160,38 +111,31 @@ Authorized person includes Further prioritization must be done, e.g. based on release planning. +.. _chm_implementation_monitoring: -.. _chm_implementation: - -Implementation of the Change Request -==================================== -If the Change Request is accepted, it must be implemented. +Implementation and Monitoring of the Change Request +=================================================== +If the Change Request is accepted, the implementation of the change must be initiated and +monitored. - -.. _chm_verification: - -Verification of the Change Request -================================== - -The defined verification measures must be use to confirm the implementation. - - -.. _chm_reporting: - -Reporting of the Change Request -=============================== +The Change Request implementation must be tracked until it is closed. The status of the Change Request must be communicated by the :need:`Technical Lead ` or :need:`Module Lead ` until the implementation is completed and confirmed. +.. _chm_closing: + +Closing of the Change Request +============================= -.. _chm_traceability: +Use the :ref:`Change Request Review Checklist ` to control the completeness of the +Change Request to be closed. -Traceability Concept for Change Requests -======================================== +Especially the effectiveness of the solution measures must be shown, based on convincing +arguments, e.g. verification measures must be used to confirm the implementation. -The standards require that a Change Request can be traced throughout the complete hierarchy levels -including all affected work products. +The standards require that a Change Request can be traced throughout the complete +hierarchy levels including all affected work products. In general the traceability is visualized in the general traceability concept (:ref:`general_concepts_traceability`). diff --git a/process/process_areas/change_management/change_management_getstrt.rst b/process/process_areas/change_management/change_management_getstrt.rst index 84490cf109..ba353e01fb 100644 --- a/process/process_areas/change_management/change_management_getstrt.rst +++ b/process/process_areas/change_management/change_management_getstrt.rst @@ -20,9 +20,31 @@ Getting Started :status: valid :tags: change_management -In case you want to contribute a change to **S-CORE** consider to: +This document describes the steps to create a change request, and further to analyze, +implement, and to control the change until closure. Where a change is defined as an +introduction of a new feature/component or modification of an existing feature/component. -* Contact the :need:`Technical Lead ` for your contribution to establish planning and reporting -* Create your change requests according to :need:`wf__change_cr_an_change_request` -* Make familiar with the development and supporting process descriptions in :ref:`process_description` -* Make familiar with the relevant sections of the `Platform Management Plan `, here especially with `Change Management Plan ` +Examples for change requests: + +* New feature e.g. communication, debugging, health management, cryptography introduced (feature request). +* Existing feature, e.g. communication supports new protocol (feature modification). +* New component for parsing a protocol introduced (component request). +* API change for an existing component (component modification). + +Therefore guidelines :need:`gd_temp__change_feature_request` and +:need:`gd_temp__change_component_request`, :need:`gd_guidl__change_change_request` and +a :need:`doc_concept__change_process` are available. + +General Workflow +**************** + +The workflows are defined in the :ref:`chm_change_workflows` section. + +For every change identified, the following workflows are executed: + +* Create your change request according to :need:`wf__change_create_cr` +* Analyze change request report according to :need:`wf__change_analyze_cr` +* Implement change request and monitor it until closure according to :need:`wf__change_implement_monitor_cr` +* Close the change request according to :need:`wf__change_close_cr` + +In addition create a change management plan as part of the platform management plan according to :need:`wf__platform_cr_mt_platform_mgmt_plan` diff --git a/process/process_areas/change_management/change_management_roles.rst b/process/process_areas/change_management/change_management_roles.rst index 85cebaee83..f1b87b088a 100644 --- a/process/process_areas/change_management/change_management_roles.rst +++ b/process/process_areas/change_management/change_management_roles.rst @@ -21,7 +21,7 @@ Contributing Roles: * :need:`Contributor ` * :need:`Committer ` - * :need:`Contributor ` + * :need:`Technical Project Lead ` * :need:`Module Project Lead ` * :need:`Safety Manager ` * :need:`Security Manager ` diff --git a/process/process_areas/change_management/change_management_workflow.rst b/process/process_areas/change_management/change_management_workflow.rst index d04982bdb5..71118f34ed 100644 --- a/process/process_areas/change_management/change_management_workflow.rst +++ b/process/process_areas/change_management/change_management_workflow.rst @@ -12,36 +12,80 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +.. _chm_change_workflows: Workflow Change Management ########################## -.. workflow:: Create/Analyze Change Request - :id: wf__change_cr_an_change_request +.. workflow:: Create Change Request + :id: wf__change_create_cr :status: valid :tags: change_management :responsible: rl__contributor :approved_by: rl__committer - :supported_by: rl__technical_lead, rl__module_lead + :supported_by: rl__technical_lead, rl__module_lead, rl__safety_manager, rl__security_manager, rl__quality_manager :input: wp__policies, wp__issue_track_system, wp__feat_request, wp__cmpt_request :output: wp__issue_track_system, wp__feat_request, wp__cmpt_request :contains: gd_guidl__change_change_request, gd_temp__change_feature_request, gd_temp__change_component_request, gd_temp__change_impact_analysis, gd_temp__component_classification, gd_req__change_attr_uid, gd_req__change_attr_status, gd_req__change_attr_title, gd_req__change_attr_impact_description, gd_req__change_attr_impact_safety, gd_req__change_attr_impact_security, gd_req__change_attr_types, gd_req__change_attr_affected_wp, gd_req__change_attr_milestone, gd_req__change_tool_impact_analysis :has: doc_concept__change_process, doc_getstrt__change_process - The Change Request is created and analyzed. + The Change Request is created. - The Change Request must be filled out based on existing templates, including affected work - products, impact on functional safety and security, schedule, risk resources and verification - measures. + For creating the Change Request template must be used. Check here for the available + templates: :need:`doc_getstrt__change_process` or :need:`gd_guidl__change_change_request`. - All affected work products are traced. + To start the analysis the Change Request status is changed to "in review" - Until the template is not filled out properly, the Change Request may be kept in “draft” from - the [Committer (rl__committer)]. The possible outcome is either a Change Request with status - “draft” or “in review”. +.. workflow:: Analyze Change Request + :id: wf__change_analyze_cr + :status: valid + :tags: change_management + :responsible: rl__contributor + :approved_by: rl__technical_lead, rl__module_lead + :supported_by: rl__committer, rl__safety_manager, rl__security_manager, rl__quality_manager + :input: wp__policies, wp__issue_track_system, wp__feat_request, wp__cmpt_request + :output: wp__issue_track_system, wp__feat_request, wp__cmpt_request + :contains: gd_guidl__change_change_request, gd_temp__change_feature_request, gd_temp__change_component_request, gd_temp__change_impact_analysis, gd_temp__component_classification, gd_req__change_attr_uid, gd_req__change_attr_status, gd_req__change_attr_title, gd_req__change_attr_impact_description, gd_req__change_attr_impact_safety, gd_req__change_attr_impact_security, gd_req__change_attr_types, gd_req__change_attr_affected_wp, gd_req__change_attr_milestone, gd_req__change_tool_impact_analysis + :has: doc_concept__change_process, doc_getstrt__change_process + + The Change Request is analyzed. + + Until the template is not filled out properly, the Change Request may be set back to + “open” from the :need:`Committer `. + + If the Change Request shall be implemented, the Change Request status is set to + "in implementation", otherwise to "rejected". + + The author of the Change Request may cancel it, thus the status is set to "rejected". + +.. workflow:: Implement and Monitor Change Request + :id: wf__change_implement_monitor_cr + :status: valid + :tags: change_management + :responsible: rl__contributor + :approved_by: rl__committer + :supported_by: rl__technical_lead, rl__module_lead, rl__safety_manager, rl__security_manager, rl__quality_manager + :input: wp__issue_track_system, wp__feat_request, wp__cmpt_request + :output: wp__issue_track_system, wp__feat_request, wp__cmpt_request + :contains: gd_guidl__change_change_request, gd_temp__change_feature_request, gd_temp__change_component_request, gd_temp__change_impact_analysis, gd_temp__component_classification, gd_req__change_attr_uid, gd_req__change_attr_status, gd_req__change_attr_title, gd_req__change_attr_impact_description, gd_req__change_attr_impact_safety, gd_req__change_attr_impact_security, gd_req__change_attr_types, gd_req__change_attr_affected_wp, gd_req__change_attr_milestone, gd_req__change_tool_impact_analysis + :has: doc_concept__change_process, doc_getstrt__change_process + + The Change Request is implemented and monitored. -.. workflow:: Review/Approve Change Request - :id: wf__change_rv_ap_change_request + This may require additional activities, including creating ISSUEs and PRs. + These are linked to the Change Request and monitored until closure. + + The Change Request is done, if all linked activities has been closed and confirmed. + Before closing the Change Request, :need:`Committer ` must check the + correctness. + + The :need:`Committer ` may still reject it, thus the status is set to + "rejected". + + The author of the Change Request may cancel it, thus the status is set to "rejected". + +.. workflow:: Close Change Request + :id: wf__change_close_cr :status: valid :tags: change_management :responsible: rl__committer @@ -52,13 +96,23 @@ Workflow Change Management :contains: gd_guidl__change_change_request, gd_temp__change_feature_request, gd_temp__change_component_request, gd_temp__change_impact_analysis, gd_temp__component_classification, gd_req__change_attr_uid, gd_req__change_attr_status, gd_req__change_attr_title, gd_req__change_attr_impact_description, gd_req__change_attr_impact_safety, gd_req__change_attr_impact_security, gd_req__change_attr_types, gd_req__change_attr_affected_wp, gd_req__change_attr_milestone, gd_req__change_tool_impact_analysis :has: doc_concept__change_process, doc_getstrt__change_process - The Change Request is evaluated based on the analysis result either approved, rejected or delayed. + The Change Request is closed. - The Change Request is implemented and verified. The defined verification measures must be - available and pass. + The Change Request is closed only, if the implementation is sufficient. That is verified + by the :need:`Committer ` finally. - The final approval is done by the [Technical Lead (rl__technical_lead)] or the - [Module Project Lead (rl__module_lead)] dependent on the scope. + Otherwise the :need:`Committer ` keeps the status "in implementation". - The possible outcome is either a Change Request with status “accepted” or “rejected” or kept - "in review". +.. needextend:: docname is not None and "process_areas/change_management" in docname + :+tags: change_management + +RAS(IC) for Change Management: +****************************** + +.. needtable:: RASIC Overview for Change Management + :tags: change_management + :filter: "change_management" in tags and type == "workflow" and is_external == False + :style: table + :sort: status + :columns: id as "Activity";responsible as "Responsible";approved_by as "Approver";supported_by as "Supporter" + :colwidths: 30,30,30,30 diff --git a/process/process_areas/change_management/change_management_workproducts.rst b/process/process_areas/change_management/change_management_workproducts.rst index 1975b970a0..e5bd9f807f 100644 --- a/process/process_areas/change_management/change_management_workproducts.rst +++ b/process/process_areas/change_management/change_management_workproducts.rst @@ -37,7 +37,7 @@ Work Products Change Management | | Safety anomaly: Conditions that deviate from expectations and that can lead to harm. | The documentation of a change request shall contain the list of changed work products, - the details of the change and the planned date of deployment of the change. + | the details of the change and the planned date of deployment of the change. .. workproduct:: Feature Request :id: wp__feat_request @@ -47,7 +47,7 @@ Work Products Change Management | - Feature request for a new feature or a feature modification | - | Change Request for a new platform feature or a modification of an existing platform feature, + | Change Request for a new feature or a modification of an existing feature, | which changes the scope of the feature. .. workproduct:: Component Request @@ -58,7 +58,7 @@ Work Products Change Management | - Component request for a new component or a component modification | - | Change Request for a new platform component or a modification of an existing platform component, + | Change Request for a new component or a modification of an existing component, | which changes the scope of the component. | Software Modules are also Components (top-level component). diff --git a/process/process_areas/change_management/guidance/change_management_decision_record_template.rst b/process/process_areas/change_management/guidance/change_management_decision_record_template.rst index be6849af0f..af10ad5eb9 100644 --- a/process/process_areas/change_management/guidance/change_management_decision_record_template.rst +++ b/process/process_areas/change_management/guidance/change_management_decision_record_template.rst @@ -14,7 +14,6 @@ .. _decision_record_template: -======================== Decision Record Template ======================== diff --git a/process/process_areas/change_management/guidance/change_management_guideline.rst b/process/process_areas/change_management/guidance/change_management_guideline.rst index a53f75cd78..2c1320ab47 100644 --- a/process/process_areas/change_management/guidance/change_management_guideline.rst +++ b/process/process_areas/change_management/guidance/change_management_guideline.rst @@ -18,35 +18,42 @@ Guideline .. gd_guidl:: Change Request Guideline :id: gd_guidl__change_change_request :status: valid + :tags: change_management :complies: std_req__iso26262__support_8414, std_req__iso26262__support_8432, std_req__iso26262__support_8442, std_req__iso26262__support_8451 + This document describes the general guidances for Change Management based on the concept which is defined :need:`[[title]]`. General Hints ============= -The detailed implementation of the Change Management for **S-CORE** is described in the `[[title]]`. +The detailed implementation of the Change Management for the project shall be described in the :ref:`Workflow Platform Management `. Templates --------- -*Need* templates displaying the correct syntax and attribute definition are provided for each -Change Request type. +To create a change request, the project shall provide the content of the following +templates in a pull request (PR) linked to an issue in the project's selected Issue +Tracking System: :need:`[[title]] ` and +:need:`[[title]] `. + +The project's selected Issue Tracking System may also use the content of these templates +to provide e.g. a change request issue template. + +.. note:: + An example template for the Issue Tracking System in GitHub (`GitHub Issues `_) + can be found here: + `Issue Template Change Request `_ + +Improvements including Process Improvements are not Change Requests. +The project's selected Issue Tracking System may also provide a template for improvements, +e.g. an improvement issue template. + +.. note:: + An example template for the Issue Tracking System in GitHub (`GitHub Issues `_) + can be found here: + `Issue Template Improvement `_ -.. list-table:: Overview - :header-rows: 1 - :widths: 37, 37 - - * - Change Request Type - - Template - * - Feature - - :need:`[[title]] ` - * - Feature Modification - - :need:`[[title]] ` - * - Component - - :need:`[[title]] ` - * - Component Modification - - :need:`[[title]] ` Attributes ---------- @@ -55,13 +62,13 @@ For all Change Requests following mandatory attributes need to be defined: .. needtable:: Overview of mandatory change request attributes :tags: change_management - :filter: "mandatory" in tags and "attribute" in tags and "chm" in tags and is_external == False + :filter: "mandatory" in tags and "attribute" in tags and "change_management" in tags and is_external == False :style: table :columns: title :colwidths: 30 -A more detailed description can be found here: :ref:`chm_process_requirements` +A more detailed description can be found here: :ref:`chm_process_change_request_attributes`. .. _workflow_chm_requirements: @@ -69,117 +76,201 @@ A more detailed description can be found here: :ref:`chm_process_requirements` Activities for Change Requests ============================== -This section describes in detail which steps need to be performed for a Change Request. They may -be combined in on Change Request or split to multiple Change Requests, if necessary. - -Split may required, if - -| 1. Implementation is to complex and has dependencies, thus separate the activities for analyzing and -| approving and the multiple implementation and verification activities in different Change Requests, -| and link them according their dependencies. - -| 2. Affected work products are in different locations. - -Refer to the `Change Management Plan ` for examples -how to create simple or more complex Change Requests. +This section describes in detail which steps need to be performed for a Change Request. .. list-table:: Activities for Change Request :header-rows: 1 - :widths: 10,60,30 + :widths: 10,60,30,30 * - Step - Description - Responsible + - Approver * - :ref:`1. ` - - Create change request + - Create Change Request - :need:`[[title]] ` + - :need:`[[title]] ` * - :ref:`2. ` - Analyze Change Request - :need:`[[title]] ` - * - :ref:`3. ` - - Approve Change Request - - :need:`[[title]] ` - * - :ref:`4. ` - - Implement Change Request + - :need:`[[title]] `, :need:`[[title]] ` + * - :ref:`3. ` + - Implement and Monitor Change Request - :need:`[[title]] ` - * - :ref:`5. ` - - Verify Change Request - :need:`[[title]] ` + * - :ref:`4. ` + - Close Change Request + - :need:`[[title]] ` + - :need:`[[title]] `, :need:`[[title]] ` + .. _chm_create_change_request: Create Change Request --------------------- -:need:`[[title]] ` creates the Change Request in the defined Issue Tracking -System linked to the created Feature or Component Request work products based on the provided templates. -It is expected, that the UID will be provided by the Issue Tracking System. - -The title of the Change Request should reflect the type (new feature/component request or -feature/component modification). +:need:`[[title]] ` (as author, submitter) creates the Change Request +as a pull request (PR) based on the content of the provided templates: +:need:`[[title]] ` or :need:`[[title]] `. +This PR is linked to an issue of the selected Issue Tracking System of the project. + +It is expected, that the status of the pull request is set to "draft" or "open" automatically. + +To start the process only to open the issue is allowed. But the issue shall then provide +already the content of the mentioned templates above. + +It is expected, that the status of the issue is set to "open" automatically. + +It is expected that the selected Issue Tracking system supports template definition. +Best practice is to define a template with the required content, so that it can be either +automatically included or copied by the different users. + +.. note:: + For the Issue Tracking System in GitHub, there is a template created, which can be + be found here: + `Issue Template Change `_ + +.. note:: + A Change Request Example based on that template is here: + `Example Change Request `_ + +It is expected, that + +* UID will be provided automatically by the Issue Tracking System. +* The status of the change request is set to "open" automatically. As long as the content is updated, the status of the change request is kept "open". +* The change request submitter will be set automatically by the Issue Tracking System. +* The title of the change request reflects the topic accordingly. +* The change request type reflects level of the change: feature or component. +* The description reflects in detail: Exact description of the Change Request including reason, impact analysis on user, effort for implementation (schedule, risks, resources) and verification (measures defined). +* A detailed impact analysis is available. + * If the change affects safety or security it should be stated explicitly. + * If safety is affected, the ASIL classification should be added, if applicable. + +.. note:: + | For the Change Request Example: + | * The UID is provided by the Issue Tracking System as: **#168** + | * The status of the issue is provided by the Issue Tracking System as: **Open** + | * The submitter is provided by the Issue Tracking System as: **masc2023** + | * the title contains the change reason, as API of a component modified + | * The change request type is selected as Component Modification + | * The descriptions considers details of the change and how the user is impacted + | * Estimations for realization are given + | * The affected high level work products are identified: Requirements, Architecture and Detailed Design + | * The detailed affected work products are listed. + | * Checkboxes are selected to highlight, that Safety is affected with classification ASIL_B + | * The expected implementation version is defined + +When ready to review and to analyze, the author sets the status to "in review" manually. + +.. note:: + | For the Change Request Example: + | * The "Process Development Community" dashboard is added and the status must be changed to **Todo** + | * The combination of the issue status **Open** and "Process Development Community" **Todo** defines the status **in review** -The description should reflect the detailed changes. In case of a new feature/component request, -fill-out the template sections properly. For modifications touch only the concerned sections. - -Set the status of the Change Request to "draft", indicating that is not ready for review. .. _chm_analyze_change_request: Analyze Change Request ---------------------- +The projects :need:`[[title]] ` or :need:`[[title]] ` supported by +:need:`[[title]] ` (includes Safety, Security and Quality Manager) analyzes the change +request together with the :need:`[[title]] ` and takes a decision with +the submitting/authoring contributor for accepting or rejecting it. -To enable the **S-CORE** :need:`[[title]] ` to take a decision for approval of the -Change Request, :need:`[[title]] ` analyses and documents the request concerning -the following topics in the created Change Request: +The analysis will start by reviewing all the information given during the creation of the +change request. All topics are revisited and checked for correctness, completeness and +consistency. -1. List of all affected work products -2. Provide potential implementation schedule including targeted Milestone -3. Identify risks for implementation, required **S-CORE** resources -4. Identify impact on existing work products and on functional safety, security -5. Define verification measures used to confirm the implementation +If required, the information is updated accordingly. -Use therefore the : :ref:`Impact Analysis Template ` and copy it -into the created Change Request (Issue Tracking System). +If accepted, the stakeholder of the change and the expected release, where the change +should be closed, shall be defined. Optionally, the corresponding milestone can be set. -Set the status of the Change Request to "draft", indicating that is not ready for review. -Otherwise, change the status to "in review", so that :need:`[[title]] ` is -informed to start approval. +.. note:: + | For the Change Request Example: + | * The stakeholder are provided using Assignees field: **masc2023** + | * The expected closure version is provided: *0.5* + | * The "Milestone" is provided: **Release 2.0.0 - Maturity Level 2** -.. _chm_approve_change_request: +If accepted, :need:`[[title]] ` can start with the implementation of the +Change Request. -Approve Change Request ----------------------- +The author has the freedom to cancel the change request at any time by setting the status to "rejected". -:need:`[[title]] ` checks the Change Request in status "in review" based on -checklist questions and provided content. If the check is passed, the Change Request is approved, -which is pre-requisite for the implementation of the Change Request. In this case the status -of the Change Request is changed to "accepted". +.. note:: + | For the Change Request Example: + | * For rejection the status of the issue must be changed to **Closed as not planned** + | * The combination of issue status **Closed as not planned** and any "Process Development Community" status defines the status **rejected** -In case information are missing the status will be kept in "in review" and the creator is asked -for resolving the review comments. -Finally the Change Request may also "rejected", then the implementation is not wanted. +.. _chm_imp_mon_change_request: -.. _chm_implement_change_request: +Implement and Monitor Change Request +------------------------------------ -Implement Change Request ------------------------- +If accepted, the projects :need:`[[title]] ` initiates the implementation +of the change together with the :need:`[[title]] `. -:need:`[[title]] ` implements the Change Request. This is indicated by the -Change Request status "in review". During implementation the responsible lead -:need:`[[title]] ` or :need:`[[title]] ` reports regularly -the status to the involved **S-CORE** teams until is completed and verified. +The description may reflect details for the implementation. -The traceability from the Change Request to the affected work products must be established -during implementation. -Also the verification measures must be executed. +.. note:: + | For the Change Request Example: + | * The descriptions has a section for **How is the change realized**, but it is empty. -.. _chm_verify_change_request: +The concrete implementation of the solution may require several additional activities. +In this case additional issues may created and linked to the Change Request. -Verify Change Request ---------------------- -:need:`[[title]] ` must finally check, that implementation is complete -and the defined verification measures are properly executed and successfully pass, before the -Change Request can be finally approved. +.. note:: + | For the Change Request Example: + | * The **Create sub-issue** should be used to create further linked issues. + +Minimal a pull request is sufficient to implement the change, which shall be linked +to the Change Request. It is expected, that the status of the pull request is set to +"draft" or "open" automatically. + +When ready to implement, the author sets the status to "in implementation" manually. + +.. note:: + | For the Change Request Example: + | * The "Process Development Community" status must be changed to **In Progress** + | * The linked Pull Request status is either "Draft" or "Open" + | * The combination of issue status **Open** and "Process Development Community" status **In Progress** and the pull request status **Draft** or **Open** defines the status **in implementation** + +.. note:: + | For the Change Request Example: + | * The **Development** section should be used to link to an pull request + | * The **Create a branch** action may used to create automatically a linked pull request + +During the implementation of the change the responsible lead :need:`[[title]] ` +or :need:`[[title]] ` reports regularly the status to the affected +projects teams. + +The author has the freedom to cancel the change request at any time by setting the status to "rejected". + + +.. _chm_close_change_request: + +Close Change Request +-------------------- + +During implementation the :need:`[[title]] ` monitors all activities linked to +the change, until they are closed. + +:need:`[[title]] ` finally checks if the Change Request implementation +is sufficient before the status is changed to closed. To check, if it is sufficient, +:need:`Change Request Checklist ` can be used. +Further the effectiveness of the implemented measure is confirmed and the availability +of the required reports, as well as verification results, if applicable. + +When confirmed, the :need:`[[title]] ` or :need:`[[title]] ` +sets the status to "closed" manually, if not done automatically. + +.. note:: + | For the Change Request Example: + | * For closing the status of the issue must be changed to **Closed** + | * The "Process Development Community" status must be changed to **Done** + | * The PR status must be changed to **Merged** + | * The combination of issue status **Closed** and "Process Development Community" status **Done** and the pull request status **Merged** defines the status **closed** -The Change Request is closed by setting the status to "accepted". +:need:`[[title]] ` has the freedom to reject it at any time by setting the status +to "reject". diff --git a/process/process_areas/change_management/guidance/change_management_reqs.rst b/process/process_areas/change_management/guidance/change_management_reqs.rst index 753c9fc989..921f9c6a36 100644 --- a/process/process_areas/change_management/guidance/change_management_reqs.rst +++ b/process/process_areas/change_management/guidance/change_management_reqs.rst @@ -12,13 +12,11 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -.. _chm_process_requirements: +.. _chm_process_change_request_attributes: Process Requirements ==================== -.. _chm_process_change_request_attributes: - Change Request Attributes ------------------------- @@ -26,7 +24,7 @@ Change Request Attributes :id: gd_req__change_attr_uid :status: valid :tags: done_automation, attribute, mandatory - :satisfies: wf__change_cr_an_change_request, wf__change_rv_ap_change_request + :satisfies: wf__change_create_cr, wf__change_analyze_cr, wf__change_implement_monitor_cr, wf__change_close_cr :complies: std_req__aspice_40__SUP-10-BP1, std_req__iso26262__support_8411, std_req__iso26262__support_8421, std_req__iso26262__support_8432, std_req__iso26262__support_8453 Each Change Request shall have a unique ID. It shall be in an integer number. @@ -35,21 +33,22 @@ Change Request Attributes :id: gd_req__change_attr_status :status: valid :tags: done_automation, attribute, mandatory - :satisfies: wf__change_cr_an_change_request, wf__change_rv_ap_change_request + :satisfies: wf__change_create_cr, wf__change_analyze_cr, wf__change_implement_monitor_cr, wf__change_close_cr :complies: std_req__aspice_40__SUP-10-BP3, std_req__aspice_40__SUP-10-BP5, std_req__aspice_40__SUP-10-BP6, std_req__iso26262__support_8411, std_req__iso26262__support_8422, std_req__iso26262__support_8432, std_req__iso26262__support_8442 Each Change Request shall have a status: - * draft + * open * in review - * accepted + * in implementation + * closed * rejected .. gd_req:: Change Request attribute: title :id: gd_req__change_attr_title :status: valid :tags: manual, attribute, mandatory - :satisfies: wf__change_cr_an_change_request, wf__change_rv_ap_change_request + :satisfies: wf__change_create_cr, wf__change_analyze_cr, wf__change_implement_monitor_cr, wf__change_close_cr :complies: std_req__aspice_40__SUP-10-BP1, std_req__iso26262__support_8411, std_req__iso26262__support_8422 Reason for the Change Request @@ -58,7 +57,7 @@ Change Request Attributes :id: gd_req__change_attr_impact_description :status: valid :tags: manual, attribute, mandatory - :satisfies: wf__change_cr_an_change_request, wf__change_rv_ap_change_request + :satisfies: wf__change_create_cr, wf__change_analyze_cr, wf__change_implement_monitor_cr, wf__change_close_cr :complies: std_req__aspice_40__SUP-10-BP2, std_req__iso26262__support_8411, std_req__iso26262__support_8422, std_req__iso26262__support_8431, std_req__iso26262__support_8432, std_req__iso26262__support_8452, std_req__iso26262__support_8453 Exact description of the Change Request, including impact analysis on functional safety, @@ -68,7 +67,7 @@ Change Request Attributes :id: gd_req__change_attr_impact_safety :status: valid :tags: prio_1_automation, attribute, mandatory - :satisfies: wf__change_cr_an_change_request, wf__change_rv_ap_change_request + :satisfies: wf__change_create_cr, wf__change_analyze_cr, wf__change_implement_monitor_cr, wf__change_close_cr :complies: std_req__aspice_40__SUP-10-BP2, std_req__iso26262__support_8422 Each Change Request shall have a automotive safety integrity level (ASIL) identifier: @@ -80,7 +79,7 @@ Change Request Attributes :id: gd_req__change_attr_impact_security :status: valid :tags: prio_2_automation, attribute, mandatory - :satisfies: wf__change_cr_an_change_request, wf__change_rv_ap_change_request + :satisfies: wf__change_create_cr, wf__change_analyze_cr, wf__change_implement_monitor_cr, wf__change_close_cr :complies: std_req__aspice_40__SUP-10-BP2, std_req__iso26262__support_8422 Each Change Request shall have a security relevance identifier: @@ -92,7 +91,7 @@ Change Request Attributes :id: gd_req__change_attr_types :status: valid :tags: prio_1_automation, attribute, mandatory - :satisfies: wf__change_cr_an_change_request, wf__change_rv_ap_change_request + :satisfies: wf__change_create_cr, wf__change_analyze_cr, wf__change_implement_monitor_cr, wf__change_close_cr :complies: std_req__aspice_40__SUP-10-BP1 * Feature @@ -100,13 +99,28 @@ Change Request Attributes * Component * Component Modification - Feature/Component means new Feature/Component + Feature + This Change Request describes a potential new feature for the platform. + The Change Request uses the Feature request template: :ref:`chm_feature_templates`. + + Feature Modification + This Change Request describes a scope modification of an existing feature (requirement + or work product). The Change Request modifies the already existing Feature Request + template: :ref:`chm_feature_templates`. + + Component + This Change Request describes a potential new component for the platform. + The Change Request uses the Component request template: :ref:`chm_component_templates`. + + Component Modification + This Change Request describes a scope modification of an existing component (requirement or work + product). The Change Request modifies the already existing Component Request template: :ref:`chm_component_templates`. .. gd_req:: Change Request attribute: Affected Work Products :id: gd_req__change_attr_affected_wp :status: draft :tags: attribute, mandatory - :satisfies: wf__change_cr_an_change_request, wf__change_rv_ap_change_request + :satisfies: wf__change_create_cr, wf__change_analyze_cr, wf__change_implement_monitor_cr, wf__change_close_cr :complies: std_req__aspice_40__SUP-10-BP4, std_req__iso26262__support_8412, std_req__iso26262__support_8422, std_req__iso26262__support_8452, std_req__iso26262__support_8453 Links to the work products affected by the Change Request @@ -115,7 +129,7 @@ Change Request Attributes :id: gd_req__change_attr_milestone :status: valid :tags: done_automation, attribute, mandatory - :satisfies: wf__change_cr_an_change_request, wf__change_rv_ap_change_request + :satisfies: wf__change_create_cr, wf__change_analyze_cr, wf__change_implement_monitor_cr, wf__change_close_cr :complies: std_req__aspice_40__SUP-10-BP6, std_req__iso26262__support_8413 Milestone until the Change Request must be implemented (used for prioritization) @@ -130,7 +144,7 @@ Change Request Checks :id: gd_req__change_attr_mandatory :status: valid :tags: prio_2_automation, attribute, check - :satisfies: wf__change_cr_an_change_request, wf__change_rv_ap_change_request + :satisfies: wf__change_create_cr, wf__change_analyze_cr, wf__change_implement_monitor_cr, wf__change_close_cr :complies: std_req__aspice_40__iic-13-51 It shall be checked if all mandatory attributes for each Change Request @@ -152,7 +166,7 @@ Change Request Traceability Impact Analysis Tool :id: gd_req__change_tool_impact_analysis :status: valid :tags: prio_3_automation, check, tool - :satisfies: wf__change_cr_an_change_request, wf__change_rv_ap_change_request + :satisfies: wf__change_create_cr, wf__change_analyze_cr, wf__change_implement_monitor_cr, wf__change_close_cr :complies: std_req__aspice_40__iic-13-51 It shall be reported, which work products and elements are affected by adding a new