diff --git a/process/folder_templates/platform/docs/change/decision_record.rst b/process/folder_templates/platform/docs/change/decision_record.rst index 530d09de83..16b9b54a11 100644 --- a/process/folder_templates/platform/docs/change/decision_record.rst +++ b/process/folder_templates/platform/docs/change/decision_record.rst @@ -32,7 +32,7 @@ In each DR file, include the following sections: :id: dec_rec____, dec_rec__<arch|proc|strat|infra|int>__<slug> :status: <proposed|accepted|deprecated|rejected|superseded> :tracking: <link to GitHub issue URL, required once a DR is confirmed> - :version: 1 + :version: 2 :affects: <link> <Description> @@ -73,10 +73,27 @@ In each DR file, include the following sections: * **<Disadvantage 2>:** <Explanation> ] + Note: + Throughout the discussion of a CR, various ideas will be proposed which are not accepted. + Those rejected ideas should be recorded along with the reasoning as to why they were rejected. + This both helps record the thought process behind the final version of the CR as well as preventing people from bringing up the same rejected idea again in subsequent discussions. + In a way this section can be thought of as a breakout section of the Rationale section that is focused specifically on why certain ideas were not ultimately pursued. + Justification for the Decision ------------------------------ <your text> + + Impact Analysis (Optional) + -------------------------- + The impact analysis template can be used to detail out the impact on the platform + and if applicable for other aspects, especially for safety/security. + Either reference here to the filled-out template or copy the content from + the template in this chapter and fill it out here. + The impact analysis template is available in [1]. + +The impact analysis template is available here [1]_. + .. attention:: The above directive must be updated according to your decision record. @@ -90,3 +107,5 @@ In each DR file, include the following sections: - Add ``Context`` to describe the issue or motivation behind this decision or change (mandatory) - Add ``decision`` to detail the proposed change or decision (mandatory) - Add ``consequences`` to explain the impact of this change, including what becomes easier or more difficult (recommended) + +.. [1] The impact analysis template is available here: :ref:`Impact Analysis Template <chm_impact_analysis_templates>` diff --git a/process/folder_templates/platform/features/feature_name/index.rst b/process/folder_templates/platform/features/feature_name/index.rst index 69cfb821ed..e3d197a7d5 100644 --- a/process/folder_templates/platform/features/feature_name/index.rst +++ b/process/folder_templates/platform/features/feature_name/index.rst @@ -22,7 +22,7 @@ .. document:: [Your Feature Name] :id: doc__feature_name :status: draft - :version: 1 + :version: 2 :safety: ASIL_B :security: YES :realizes: wp__feat_request[version==1] @@ -77,16 +77,6 @@ Motivation Motivation may based on criteria as resource requirements, scheduling issues, risks, benefits, etc. CRs submissions without sufficient motivation may be rejected. -Rationale -========= - -[Describe why particular design decisions were made.] - -.. note:: - The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion. - For the documentation of the decision the :need:`gd_temp__change_decision_record` can be used. - - Specification ============= @@ -97,61 +87,6 @@ Specification A CR shall specify the stakeholder requirements as part of our platform/project. Thereby the :need:`rl__project_lead` will approve these requirements as part of accepting the CR (e.g. merging the PR with the CR). -Backwards Compatibility -======================= - -[Describe potential impact (especially including safety and security impacts) and severity on pre-existing platform/project elements.] - - -Security Impact -=============== - -[How could a malicious user take advantage of this new/modified feature?] - -.. note:: - If there are security concerns in relation to the CR, those concerns should be explicitly written out to make sure reviewers of the CR are aware of them. - -Which security requirements are affected or has to be changed? -Could the new/modified feature enable new threat scenarios? -Could the new/modified feature enable new attack paths? -Could the new/modified feature impact functional safety? -If applicable, which additional security measures must be implemented to mitigate the risk? - -.. note:: - Use Trust Boundary, Defense in Depth Analysis and/or Security Software Critically Analysis, - Vulnerability Analysis. - [Methods will be defined later in Process area Security Analysis] - These analyses may not be available at the time of creation of the feature (request) but content will be improved iteratively. - -Safety Impact -============= - -[How could the safety be impacted by the new/modified feature?] - -.. note:: - If there are safety concerns in relation to the CR, those concerns should be explicitly written out to make sure reviewers of the CR are aware of them. - Link here to the filled out :need:`Impact Analysis Template <gd_temp__change_impact_analysis>` or copy the template in this chapter. - -Which safety requirements are affected or has to be changed? -Could the new/modified feature be a potential common cause or cascading failure initiator? -If applicable, which additional safety measures must be implemented to mitigate the risk? - -.. note:: - Use Dependency Failure Analysis and/or Safety Software Critically Analysis. - [Methods will be defined later in Process area Safety Analysis] - These analyses may not be available at the time of creation of the feature (request) but content will be improved iteratively. - -For new feature contributions: - -[What is the expected ASIL level?] - - -License Impact -============== - -[How could the copyright impacted by the license of the new contribution?] - - How to Teach This ================= @@ -160,28 +95,6 @@ How to Teach This .. note:: For a CR that adds new functionality or changes behaviour, it is helpful to include a section on how to teach users, new and experienced, how to apply the CR to their work. - -Rejected Ideas -============== - -[Why certain ideas that were brought while discussing this CR were not ultimately pursued.] - -.. note:: - Throughout the discussion of a CR, various ideas will be proposed which are not accepted. - Those rejected ideas should be recorded along with the reasoning as to why they were rejected. - This both helps record the thought process behind the final version of the CR as well as preventing people from bringing up the same rejected idea again in subsequent discussions. - In a way this section can be thought of as a breakout section of the Rationale section that is focused specifically on why certain ideas were not ultimately pursued. - -Open Issues -=========== - -[Any points that are still being decided/discussed.] - -.. note:: - While a CR is in draft, ideas can come up which warrant further discussion. - Those ideas should be recorded so people know that they are being thought about but do not have a concrete resolution. - This helps make sure all issues required for the CR to be ready for consideration are complete and reduces people duplicating prior discussion. - Footnotes ========= diff --git a/process/process_areas/change_management/change_management_concept.rst b/process/process_areas/change_management/change_management_concept.rst index 1eeb10f56c..bc47487370 100644 --- a/process/process_areas/change_management/change_management_concept.rst +++ b/process/process_areas/change_management/change_management_concept.rst @@ -18,7 +18,7 @@ Concept Description .. doc_concept:: Concept Description :id: doc_concept__change_process :status: valid - :version: 1 + :version: 2 :tags: change_management In this section a concept for the Change Management will be discussed. Inputs for this concepts @@ -33,6 +33,10 @@ As features are built-up by components a Change Request is also needed to add ne components or to modify the scope of existing components. All statements here for components are also valid for *SW Modules*. +As a rule of thumb, a Change Request is needed, if feature or component requirements +are changed in a way that also will cause version update +(compare :ref:`significant_requirement_changes`). + Inputs ****** @@ -95,12 +99,15 @@ Activities for a Change Request Creation of the Change Request ============================== -Use the content :ref:`Feature Request Template <chm_feature_templates>` or -:ref:`Component Request Template <chm_component_templates>` to create a Change Request. + +Use the content :ref:`Decision Record Template <decision_record_template>` to create a +Change Request. In case safety or security is affected, in addition the impact analysis template : :ref:`Impact Analysis Template <chm_impact_analysis_templates>` can be used to detail -out the impact on safety/security. +out the impact on platform, or any other aspect including especially safety/security. +The template can be referenced in the decision record or copied into the decision record +and filled out there. The impact analysis tool (:need:`gd_req__change_tool_impact_analysis`) can support to here to identify the affected work products. @@ -131,6 +138,12 @@ monitored. The Change Request implementation must be tracked until it is closed. +Use the content :ref:`Feature Request Template <chm_feature_templates>` or +:ref:`Component Request Template <chm_component_templates>` to document the creation +of a new feature or component. In case of modification of an existing feature or +component, the same templates (which should be already existing) can be used to +document the modification. + The status of the Change Request must be communicated by the :need:`Project Lead <rl__project_lead>` (for feature requests) and the lead of the :need:`Delivery Team <rl__delivery_team>` (for component requests) until diff --git a/process/process_areas/change_management/change_management_getstrt.rst b/process/process_areas/change_management/change_management_getstrt.rst index 2bd3cb384d..218889ecdd 100644 --- a/process/process_areas/change_management/change_management_getstrt.rst +++ b/process/process_areas/change_management/change_management_getstrt.rst @@ -18,7 +18,7 @@ Getting Started .. doc_getstrt:: Getting Started on Change Management :id: doc_getstrt__change_process :status: valid - :version: 1 + :version: 2 :tags: change_management This document describes the steps to create a change request, and further to analyze, @@ -32,9 +32,11 @@ Examples for change requests: * 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 + +Therefore a template :need:`gd_temp__change_decision_record` is available. This template +is complemented by the :need:`gd_temp__change_feature_request`, :need:`gd_temp__change_component_request`, :need:`gd_guidl__change_change_request` and -a :need:`doc_concept__change_process` are available. +:need:`doc_concept__change_process`. General Workflow **************** diff --git a/process/process_areas/change_management/change_management_workflow.rst b/process/process_areas/change_management/change_management_workflow.rst index 1ab9dd64c4..66acecbadd 100644 --- a/process/process_areas/change_management/change_management_workflow.rst +++ b/process/process_areas/change_management/change_management_workflow.rst @@ -33,12 +33,12 @@ For a detailed explanation of workflows and their role within the process model, wp__cmpt_request[version==1] :output: wp__issue_track_system[version==1], wp__feat_request[version==1], wp__cmpt_request[version==1] :contains: gd_guidl__change_change_request[version==1], - gd_temp__change_feature_request[version==1], + gd_temp__change_feature_request[version==2], gd_temp__change_component_request[version==1], - gd_temp__change_impact_analysis[version==1], + gd_temp__change_impact_analysis[version==2], gd_temp__component_classification[version==1], - gd_temp__change_decision_record[version==1] - :has: doc_concept__change_process[version==1], doc_getstrt__change_process[version==1] + gd_temp__change_decision_record[version==2] + :has: doc_concept__change_process[version==2], doc_getstrt__change_process[version==2] The Change Request is created. @@ -61,12 +61,12 @@ For a detailed explanation of workflows and their role within the process model, wp__cmpt_request[version==1] :output: wp__issue_track_system[version==1], wp__feat_request[version==1], wp__cmpt_request[version==1] :contains: gd_guidl__change_change_request[version==1], - gd_temp__change_feature_request[version==1], + gd_temp__change_feature_request[version==2], gd_temp__change_component_request[version==1], - gd_temp__change_impact_analysis[version==1], + gd_temp__change_impact_analysis[version==2], gd_temp__component_classification[version==1], - gd_temp__change_decision_record[version==1] - :has: doc_concept__change_process[version==1], doc_getstrt__change_process[version==1] + gd_temp__change_decision_record[version==2] + :has: doc_concept__change_process[version==2], doc_getstrt__change_process[version==2] The Change Request is analyzed. @@ -90,12 +90,12 @@ For a detailed explanation of workflows and their role within the process model, :input: wp__issue_track_system[version==1], wp__feat_request[version==1], wp__cmpt_request[version==1] :output: wp__issue_track_system[version==1], wp__feat_request[version==1], wp__cmpt_request[version==1] :contains: gd_guidl__change_change_request[version==1], - gd_temp__change_feature_request[version==1], + gd_temp__change_feature_request[version==2], gd_temp__change_component_request[version==1], - gd_temp__change_impact_analysis[version==1], + gd_temp__change_impact_analysis[version==2], gd_temp__component_classification[version==1], - gd_temp__change_decision_record[version==1] - :has: doc_concept__change_process[version==1], doc_getstrt__change_process[version==1] + gd_temp__change_decision_record[version==2] + :has: doc_concept__change_process[version==2], doc_getstrt__change_process[version==2] The Change Request is implemented and monitored. @@ -129,12 +129,12 @@ For a detailed explanation of workflows and their role within the process model, :input: wp__issue_track_system[version==1], wp__feat_request[version==1], wp__cmpt_request[version==1] :output: wp__issue_track_system[version==1], wp__feat_request[version==1], wp__cmpt_request[version==1] :contains: gd_guidl__change_change_request[version==1], - gd_temp__change_feature_request[version==1], + gd_temp__change_feature_request[version==2], gd_temp__change_component_request[version==1], - gd_temp__change_impact_analysis[version==1], + gd_temp__change_impact_analysis[version==2], gd_temp__component_classification[version==1], - gd_temp__change_decision_record[version==1] - :has: doc_concept__change_process[version==1], doc_getstrt__change_process[version==1] + gd_temp__change_decision_record[version==2] + :has: doc_concept__change_process[version==2], doc_getstrt__change_process[version==2] The Change Request is closed. 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 a7238aaa6a..f9daf005ce 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 @@ -20,7 +20,7 @@ Decision Record Template .. gd_temp:: Decision Record Template :id: gd_temp__change_decision_record :status: valid - :version: 1 + :version: 2 :complies: std_req__aspice_40__SWE-2-BP3[version==1], std_req__aspice_40__iic-17-00[version==1] For the content see here: :ref:`decision_record_template`. diff --git a/process/process_areas/change_management/guidance/change_management_feature_template.rst b/process/process_areas/change_management/guidance/change_management_feature_template.rst index 4ae4f94682..005fea45ee 100644 --- a/process/process_areas/change_management/guidance/change_management_feature_template.rst +++ b/process/process_areas/change_management/guidance/change_management_feature_template.rst @@ -20,7 +20,7 @@ Feature Template .. gd_temp:: Feature Request Template :id: gd_temp__change_feature_request :status: valid - :version: 1 + :version: 2 :complies: std_req__aspice_40__SUP-10-BP1[version==1], std_req__aspice_40__SUP-10-BP2[version==1], std_req__aspice_40__SUP-10-BP3[version==1], diff --git a/process/process_areas/change_management/guidance/change_management_impact_analysis_template.rst b/process/process_areas/change_management/guidance/change_management_impact_analysis_template.rst index 4f9778660c..085ca3b917 100644 --- a/process/process_areas/change_management/guidance/change_management_impact_analysis_template.rst +++ b/process/process_areas/change_management/guidance/change_management_impact_analysis_template.rst @@ -20,7 +20,7 @@ Impact Analysis Template .. gd_temp:: Impact Analysis Template :id: gd_temp__change_impact_analysis :status: valid - :version: 1 + :version: 2 :complies: std_req__aspice_40__SUP-10-BP2[version==1], std_req__aspice_40__iic-18-57[version==1], std_req__iso26262__support_8431[version==1], @@ -72,16 +72,59 @@ Estimates for Realization A draft realization plan may support the realization proposal. +Potential Impact on the platform +-------------------------------- + +[How could the platform be impacted by the new/modified feature?] + +[Describe potential impact and severity on pre-existing platform/project elements.] + + Potential Impact on Security ----------------------------- -Add the potential impact in the chapter Security Impact of the concerned Feature Request -(compare :need:`Feature Request Template <gd_temp__change_feature_request>`) or Component Request -(compare :need:`Component Request Template <gd_temp__change_component_request>`). +[How could a malicious user take advantage of this new/modified feature?] + +.. note:: + If there are security concerns in relation to the CR, those concerns should be explicitly written out to make sure reviewers of the CR are aware of them. + +Which security requirements are affected or has to be changed? +Could the new/modified feature enable new threat scenarios? +Could the new/modified feature enable new attack paths? +Could the new/modified feature impact functional safety? +If applicable, which additional security measures must be implemented to mitigate the risk? + +.. note:: + Use Trust Boundary, Defense in Depth Analysis and/or Security Software Critically Analysis, + Vulnerability Analysis. + [Methods will be defined later in Process area Security Analysis] + These analyses may not be available at the time of creation of the feature (request) but content will be improved iteratively. + Potential Impact on Safety -------------------------- -Add the potential impact in the chapter Safety Impact of the concerned Feature Request -(compare :need:`Feature Request Template <gd_temp__change_feature_request>`) or Component Request -(compare :need:`Component Request Template <gd_temp__change_component_request>`). +[How could the safety be impacted by the new/modified feature?] + +.. note:: + If there are safety concerns in relation to the CR, those concerns should be explicitly written out to make sure reviewers of the CR are aware of them. + Link here to the filled out :need:`Impact Analysis Template <gd_temp__change_impact_analysis>` or copy the template in this chapter. + +Which safety requirements are affected or has to be changed? +Could the new/modified feature be a potential common cause or cascading failure initiator? +If applicable, which additional safety measures must be implemented to mitigate the risk? + +.. note:: + Use Dependency Failure Analysis and/or Safety Software Critically Analysis. + [Methods will be defined later in Process area Safety Analysis] + These analyses may not be available at the time of creation of the feature (request) but content will be improved iteratively. + +For new feature contributions: + +[What is the expected ASIL level?] + + +License Impact +============== + +[How could the copyright impacted by the license of the new contribution?] diff --git a/process/process_areas/safety_management/safety_management_workflow.rst b/process/process_areas/safety_management/safety_management_workflow.rst index a086692bfb..8ea0397de7 100644 --- a/process/process_areas/safety_management/safety_management_workflow.rst +++ b/process/process_areas/safety_management/safety_management_workflow.rst @@ -161,7 +161,7 @@ Safety Management Workflows wp__sw_component_class[version==1], wp__safety_tailoring[version==1] :output: wp__issue_track_system[version==1] - :contains: gd_temp__change_component_request[version==1], gd_temp__change_decision_record[version==1], gd_temp__change_impact_analysis[version==1] + :contains: gd_temp__change_component_request[version==1], gd_temp__change_decision_record[version==2], gd_temp__change_impact_analysis[version==2] :has: doc_concept__safety_management_process[version==1], doc_getstrt__safety_management_process[version==1] | In accordance with ISO 26262-2:2018 section 5.2.2.3 d/e (Impact Analysis), the project implements a dedicated workflow for analyzing change requests.