From ad627b4c04a956305f431a43ce35b16886153bc6 Mon Sep 17 00:00:00 2001 From: "markus.schu" Date: Thu, 27 Feb 2025 07:19:46 +0100 Subject: [PATCH] process: add intial change management process Change Management is part of the Platform Management Plan All activities in S-CORE ar driven by Change Requests Resolves: #312 --- .../contribution_request.rst | 8 +- .../templates/feature_request_template.rst | 138 --------- .../contribution_request/templates/index.rst | 2 - .../score_change_request_overview.drawio.svg | 4 + ...ange_request_workflow_complex_1.drawio.svg | 4 + ...ange_request_workflow_complex_2.drawio.svg | 4 + ..._change_request_workflow_simple.drawio.svg | 4 + .../change_management.rst | 269 +++++++++++++++++- docs/process/index.rst | 2 +- .../change_management_concept.rst | 195 +++++++++++++ .../change_management_getstrt.rst | 28 ++ .../change_management_roles.rst | 32 +++ .../change_management_workflow.rst | 64 +++++ .../change_management_workproducts.rst | 55 ++++ .../guidance/change_management_checklist.rst | 81 ++++++ .../change_management_component_template.rst | 165 +++++++++++ .../change_management_feature_template.rst | 176 ++++++++++++ .../guidance/change_management_guideline.rst | 173 +++++++++++ ...ge_management_impact_analysis_template.rst | 112 ++++++++ .../guidance/change_management_reqs.rst | 160 +++++++++++ .../change_management/guidance/index.rst | 26 ++ .../process_areas/change_management/index.rst | 29 ++ docs/process/process_areas/index.rst | 5 +- .../guidance/template_feature_safety_wp.rst | 2 +- docs/process/workproducts/index.rst | 22 -- 25 files changed, 1584 insertions(+), 176 deletions(-) delete mode 100644 docs/contribute/contribution_request/templates/feature_request_template.rst create mode 100644 docs/platform_management_plan/_assets/score_change_request_overview.drawio.svg create mode 100644 docs/platform_management_plan/_assets/score_change_request_workflow_complex_1.drawio.svg create mode 100644 docs/platform_management_plan/_assets/score_change_request_workflow_complex_2.drawio.svg create mode 100644 docs/platform_management_plan/_assets/score_change_request_workflow_simple.drawio.svg create mode 100644 docs/process/process_areas/change_management/change_management_concept.rst create mode 100644 docs/process/process_areas/change_management/change_management_getstrt.rst create mode 100644 docs/process/process_areas/change_management/change_management_roles.rst create mode 100644 docs/process/process_areas/change_management/change_management_workflow.rst create mode 100644 docs/process/process_areas/change_management/change_management_workproducts.rst create mode 100644 docs/process/process_areas/change_management/guidance/change_management_checklist.rst create mode 100644 docs/process/process_areas/change_management/guidance/change_management_component_template.rst create mode 100644 docs/process/process_areas/change_management/guidance/change_management_feature_template.rst create mode 100644 docs/process/process_areas/change_management/guidance/change_management_guideline.rst create mode 100644 docs/process/process_areas/change_management/guidance/change_management_impact_analysis_template.rst create mode 100644 docs/process/process_areas/change_management/guidance/change_management_reqs.rst create mode 100644 docs/process/process_areas/change_management/guidance/index.rst create mode 100644 docs/process/process_areas/change_management/index.rst diff --git a/docs/contribute/contribution_request/contribution_request.rst b/docs/contribute/contribution_request/contribution_request.rst index 55e090943ff..c69ca115fdc 100644 --- a/docs/contribute/contribution_request/contribution_request.rst +++ b/docs/contribute/contribution_request/contribution_request.rst @@ -35,11 +35,7 @@ For more complex contributions, like adding a new feature: For a feature request, use the template provided below and add it to the appropriate section under docs/features. -.. toctree:: - :maxdepth: 1 - :glob: - - templates/feature_request_template.rst +:ref:`Feature Request Template ` If possible, the reviewer should use the suggestion functionality to suggest a change that the author of the pull request can click to commit if they agree with your suggestion. @@ -61,7 +57,7 @@ For a *PR* to be merged, in any case an approval of a committer is needed. If th *GitHub Issue* are categorized using various types. For categorizing of PRs using of labels, e.g. bug or improvement, is mandatory, see `Platform Management Plan `_. -For all possibilites the project contains simple templates (provided by committers (:need:`Committer `)), in particular please use :ref:`Feature Request Template ` to request a new feature or changes to the existing one. +For all possibilites the project contains simple templates (provided by committers (:need:`Committer `)), in particular please use :need:`Feature Request Template ` to request a new feature or changes to the existing one. ***************************** What is a Pull Request (PR)? diff --git a/docs/contribute/contribution_request/templates/feature_request_template.rst b/docs/contribute/contribution_request/templates/feature_request_template.rst deleted file mode 100644 index 2277dee4b18..00000000000 --- a/docs/contribute/contribution_request/templates/feature_request_template.rst +++ /dev/null @@ -1,138 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2024 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 - # ******************************************************************************* - -.. _feature_request_template: - -Feature Request Template -######################## - -.. gd_temp:: Feature Request Template - :id: gd_temp__feat_request_template - :status: valid - :tags: contribution_request - -.. attention:: - Remove everything above when copying and filling the template. - -[Your Feature Name] -=================== - -.. code-block:: rst - - .. document:: [Your Feature Name] - :id: doc__your_feature_name - :status: Your_Status - :safety: Your_ASIL - :tags: contribution_request, feature_request - -.. attention:: - The above directive must be updated according to your Feature. - - - Modify ``name`` to be your Feature Name - - Modify ``id`` to be your Feature Name in upper snake case preceded by ``DOC_`` - - Adjust ``status`` to be ``valid`` - - Adjust ``asil`` according to your needs - - Extend ``tags`` according to your needs, but please keep two default tags there - - -Feature flag -============ - -To activate this feature, use the following feature flag: - -``experimental_[your_feature_name]`` - - .. note:: - The feature flag must reflect the feature name in snake_case. Further, it is prepended with ``experimental_``, as - long as the feature is not yet stable. See :ref:`feature_flags` for more information. - - -Abstract -======== - -[A short (~200 word) description of the contribution being addressed.] - - -Motivation -========== - -[Clearly explain why the existing platform/project solution is inadequate to address the topic that the Feature Request solves.] - - .. note:: - The motivation is critical for Feature Requests that want to change the existing features or infrastructure. - It should clearly explain why the existing solution is inadequate to address the topic that the Feature Request solves. - Feature Request 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. - - -Specification -============= - -[Describe the requirements, architecture of any new feature.] or -[Describe the change to requirements, architecture, implementation, process, documentation, infrastructure of any change request.] - - .. note:: - A Feature Request shall specify the stakeholder requirements as part of our platform/project. - Thereby the :need:`rl__technical_lead` will approve these requirements as part of accepting the Feature Request (e.g. merging the PR with the Feature Request). - - -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 feature?] - - .. note:: - If there are security concerns in relation to the Feature Request, those concerns should be explicitly written out to make sure reviewers of the Feature Request are aware of them. - - - -Safety Impact -============= - -[How could the safety be impacted by the new feature?] - - .. note:: - If there are safety concerns in relation to the Feature Request, those concerns should be explicitly written out to make sure reviewers of the Feature Request are aware of them. - ToDo - Link to the Safety Impact Method - -[What is the expected ASIL level?] -[What is the expected classification of the contribution?] - - .. note:: - Use the component classification method here to classfiy your component, if it shall to be used in a safety context: (TODO: add link to component classification). - - -License Impact -============== - -[How could the copyright impacted by the license of the new contribution?] - - -How to Teach This -================= diff --git a/docs/contribute/contribution_request/templates/index.rst b/docs/contribute/contribution_request/templates/index.rst index 5f873f6a4e0..b1611155e97 100644 --- a/docs/contribute/contribution_request/templates/index.rst +++ b/docs/contribute/contribution_request/templates/index.rst @@ -19,5 +19,3 @@ Contribution Templates .. toctree:: :maxdepth: 1 - - feature_request_template.rst diff --git a/docs/platform_management_plan/_assets/score_change_request_overview.drawio.svg b/docs/platform_management_plan/_assets/score_change_request_overview.drawio.svg new file mode 100644 index 00000000000..38dc8ac4282 --- /dev/null +++ b/docs/platform_management_plan/_assets/score_change_request_overview.drawio.svg @@ -0,0 +1,4 @@ + + + +
ISSUE
ISSUE
PR
PR
Change
Request
Change...
Plan, Control, Monitor
Plan, Control, Monit...
Implement, Verify
(Affected work products)
Implement, Verify...
PR
PR
Implement, Verify
(Affected work products)
Implement, Verify...
Feature/Component Request
Templates, Checklists
Feature/Component Re...
:
:
SUB-
ISSUE
SUB-...
ISSUE
ISSUEText is not SVG - cannot display \ No newline at end of file diff --git a/docs/platform_management_plan/_assets/score_change_request_workflow_complex_1.drawio.svg b/docs/platform_management_plan/_assets/score_change_request_workflow_complex_1.drawio.svg new file mode 100644 index 00000000000..9cdf1931f93 --- /dev/null +++ b/docs/platform_management_plan/_assets/score_change_request_workflow_complex_1.drawio.svg @@ -0,0 +1,4 @@ + + + +










CR status:
accepted
















CR status:...





CR status:
in review












CR status:...










CR status:
accepted
















CR status:...




















CR status:
draft

























CR status:...





CR status:
in review












CR status:...
ISSUE
[OPEN]
ISSUE...
creates
creates
Contributor
Contributor
Change
Request
(CR)
Change...
PR #1
[DRAFT]
PR #1...
PR #1
[OPEN]
PR #1...
PR #1
[MERGED]
PR #1...
ISSUE
[CLOSED]
ISSUE...
PR #2
[DRAFT]
PR #2...
PR #2
[OPEN]
PR #2...
PR #2
[MERGED]
PR #2...
SUB-ISSUE #1
[OPEN]
SUB-ISSUE #1...
SUB-ISSUE #2
[OPEN]
SUB-ISSUE #2...
SUB-ISSUE #1
[CLOSED]
SUB-ISSUE #1...
SUB-ISSUE #1
[OPEN]
SUB-ISSUE #1...




















CR status:
draft

























CR status:...




















CR status:
draft

























CR status:...





CR status:
in review












CR status:...
SUB-ISSUE #2
[CLOSED]
SUB-ISSUE #2...
SUB-ISSUE #2
[OPEN]
SUB-ISSUE #2...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/platform_management_plan/_assets/score_change_request_workflow_complex_2.drawio.svg b/docs/platform_management_plan/_assets/score_change_request_workflow_complex_2.drawio.svg new file mode 100644 index 00000000000..8ff6d27471c --- /dev/null +++ b/docs/platform_management_plan/_assets/score_change_request_workflow_complex_2.drawio.svg @@ -0,0 +1,4 @@ + + + +




















CR status:
draft

























CR status:...










CR status:
accepted
















CR status:...





CR status:
in review












CR status:...










CR status:
accepted
















CR status:...










CR status:
accepted
















CR status:...




















CR status:
draft

























CR status:...





CR status:
in review












CR status:...
<SCORE-REPO>
ISSUE
[OPEN]
<SCORE-REPO>...
creates
creates
Contributor
Contributor
Change
Request
(CR)
Change...
<SCORE-REPO>
PR
[DRAFT]
<SCORE-REPO>...
<SCORE-REPO>
PR
[OPEN]
<SCORE-REPO>...
<SCORE-REPO>
PR
[MERGED]
<SCORE-REPO>...
<SCORE-REPO>
[CLOSED]
<SCORE-REPO>...





CR status:
in review












CR status:...
<MODULE-REPO>
ISSUE
[OPEN]
<MODULE-REPO>...
<MODULE-REPO>
PR
[DRAFT]
<MODULE-REPO>...
<MODULE-REPO>
PR
[OPEN]
<MODULE-REPO>...
<MODULE-REPO>
PR
[MERGED]
<MODULE-REPO>...
<SCORE-REPO>
SUB-ISSUE
[OPEN]
<SCORE-REPO>...
<SCORE-REPO>
SUB-ISSUE
[OPEN]
<SCORE-REPO>...
<SCORE-REPO>
[CLOSED]
<SCORE-REPO>...
<MODULE-REPO>
ISSUE
[OPEN]
<MODULE-REPO>...
<MODULE-REPO>
[CLOSED]
<MODULE-REPO>...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/platform_management_plan/_assets/score_change_request_workflow_simple.drawio.svg b/docs/platform_management_plan/_assets/score_change_request_workflow_simple.drawio.svg new file mode 100644 index 00000000000..e13c7a3e183 --- /dev/null +++ b/docs/platform_management_plan/_assets/score_change_request_workflow_simple.drawio.svg @@ -0,0 +1,4 @@ + + + +










CR status:
accepted
















CR status:...




















CR status:
draft

























CR status:...





CR status:
in review










CR status:...
ISSUE
[OPEN]
ISSUE...
creates
creates
Contributor
Contributor
Change
Request
(CR)
Change...
PR
[DRAFT]
PR...
PR
[OPEN]
PR...
PR
[MERGED]
PR...
ISSUE
[CLOSED]
ISSUE...
ISSUE
[OPEN]
ISSUE...





CR status:
rejected










CR status:...
ISSUE
[CLOSED]
ISSUE...
PR
[Closed]
PR...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/platform_management_plan/change_management.rst b/docs/platform_management_plan/change_management.rst index 392e4dd7c2d..876673344e3 100644 --- a/docs/platform_management_plan/change_management.rst +++ b/docs/platform_management_plan/change_management.rst @@ -1,6 +1,6 @@ .. # ******************************************************************************* - # Copyright (c) 2024 Contributors to the Eclipse Foundation + # Copyright (c) 2025 Contributors to the Eclipse Foundation # # See the NOTICE file(s) distributed with this work for additional # information regarding copyright ownership. @@ -12,14 +12,275 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Change management ------------------------- +.. document:: Change Management Plan + :id: doc__platform_change_management_plan + :status: draft + :safety: ASIL_B + :tags: platform_management + +Change Management / Change Management Plan +------------------------------------------ + +This document implements parts of the :need:`wp__platform_mgmt`. Purpose +++++++ +The purpose of the Change Management Plan is to guide the execution of the +Change Requests of a project including their creation, analysis, approval, implementation, +and verification. + -Objectives and scope +Objectives and Scope ++++++++++++++++++++ +Change Management Goals +^^^^^^^^^^^^^^^^^^^^^^^ + +* Requests for Changes are recorded and identified. +* Change Requests are analyzed, dependencies and relationships to work products or other Change + Requests are identified, and the impact is estimated. +* Change Requests are approved before implementation and prioritized accordingly. +* Bidirectional traceability is established between Change Requests and affected work products. +* Implementation of Change Requests is confirmed. +* Change Requests are tracked to closure and status of Change Requests is communicated to + affected parties. +* Requests for Changes are properly documented. + Approach ++++++++ + +Change Request Execution +^^^^^^^^^^^^^^^^^^^^^^^^ + +Contributions in general to the **S-CORE** project are described here +(compare :need:`gd_guidl__contr_request_guideline`). + +A Change Request is a specific contribution, and +it is the **ONLY** way to contribute new features/components or to modify the scope of existing +features/components in the **S-CORE** project. + +Change Request Infrastructure and Types +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:need:`GitHub Issues (ISSUE) ` are used for managing Change Requests. +The tool is used to create, plan, control, and monitor Change Requests within **S-CORE**. + +:need:`GitHub Pull Requests (PR) ` are used for the implementation +of Change Requests. The tool is used to implement and verify Change Requests within **S-CORE**. + +The next figure gives an overview, how Change Requests are realized in **S-CORE**. An ISSUE is +used to create a Change Request including required attributes as defined in +:ref:`chm_process_change_request_attributes`. +The ISSUE may be linked to other ISSUEs or SUB-ISSUEs, if required, to manage more complex Change +Requests. The implementation of a Change Request requires at least one PR linked to the ISSUE created +for the Change Request. + +.. figure:: _assets/score_change_request_overview.drawio.svg + :width: 100% + :align: center + :alt: Change Request Overview + + Change Request Overview + +Changes are clustered in the following types: + +.. list-table:: Change Request Types + :header-rows: 1 + :widths: 15,85,15 + + * - Type + - Description + - Infrastructure + * - Feature + - Created by :need:`Contributor ` to change requirements and work products, new feature + - ISSUE with label ``feature_request`` + * - Feature Modification + - Created by :need:`Contributor ` to change requirements and work products, scope change + - ISSUE with label ``feature_modification`` + * - Component + - Created by :need:`Contributor ` to change requirements and work products, new component + - ISSUE with label ``component_request`` + * - Component Modification + - Created by :need:`Contributor ` to change requirements and work products, scope change + - ISSUE with label ``component_modification`` + + +Change Request Traceability Impact Analysis requires the following tools: + +:need:`[[title]] ` + +Change Request Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^ +:ref:`chm_process_change_request_attributes` are implemented as follows: + +:need:`[[title]] ` is identical to the ISSUE number. + +:need:`[[title]] ` is defined by the combination of the ISSUE state +and the states of the linked PRs. + +:need:`[[title]] ` is identical to the ISSUE title. + +:need:`[[title]] ` is defined in the linked PR or part of the +description. + +:need:`[[title]] ` is defined in the linked PR or part of the +description. + +:need:`[[title]] ` is defined in the linked PR or part of the +description. + +:need:`[[title]] ` is defined by label of a ISSUE and part of the +description. + +:need:`[[title]] ` is defined in the linked PR or part of the +description. + +:need:`[[title]] ` is defined by the Milestone of a ISSUE. + + +Change Request Workflow +^^^^^^^^^^^^^^^^^^^^^^^ + +In General, every Change Request follows the following steps: + +* 1. Create the Change Request +* 2. Review the Change Request +* 3. Approve the Change Request + + +**To 1. Create the Change Request:** + +An ISSUE is the **ONLY** way to create and manage a Change Request in **S-CORE**. +A PR is the **ONLY** way to implement a Change Request in **S-CORE**, +thus an ISSUE must be linked at least to one or more PRs. + +The figure below shows the workflow for the simplest case of a Change Request. + +An ISSUE with the label according to the Change Request type is created in status ``OPEN``. +The title of the ISSUE reflects the potential change. The description of the ISSUE may give a brief +description of the requested change or modification. + +The details are part of the Feature/Component Request work product. The Feature/Component Request +is provided by a PR, which is linked to the ISSUE in status ``DRAFT``. + +For a new Feature/Component Request the provided templates :ref:`Feature Request`, +:ref:`Component Request` must be used. For a modification of an existing +Feature/Component, update the existing work products. + +The linked PR in status ``DRAFT``, which contains the Feature/Component Requests, may contain also +other required affected and changed work products or implementation and verification proposals. + +Planning is done by setting the milestone of the ISSUE accordingly. + +As long as the :need:`Contributor ` wants to modify the content of the Change +Request, the linked PR is kept in status ``DRAFT``. + +Change request status: ``draft`` is implemented as +ISSUE status ``OPEN`` and PR status ``DRAFT``. + +To trigger the next step the PR status is changed from ``DRAFT`` to ``OPEN``. + +.. figure:: _assets/score_change_request_workflow_simple.drawio.svg + :width: 100% + :align: center + :alt: Change Request Simple Workflow Overview + + Change Request Simple Workflow Overview + + +**To 2. Review the Change Request:** + +The Change Request is reviewed from the :need:`Committer ` and the +review results are resolved by the :need:`Contributor `. The review results +are documented in the PR. As long as the information is not sufficient, the related PR is kept in +status ``OPEN``. + +:ref:`chm_checklist` can help to verify whether the information is complete. + +The realisation parts of the Change Request are reviewed according the checklists of the affected +work products. Verification of the realisation parts must be successful. +If the verification is not sufficient, the related PR is kept in status ``OPEN`` or may changed +back to ``DRAFT`` (compare :need:`gd_guidl__issue_guideline`). + +Change request status: ``in review`` is implemented as +ISSUE status ``OPEN`` and PR status ``OPEN``. + + +**To 3. Approve the Change Request:** +:need:`Technical Lead ` or :need:`Module Lead ` decides finally, +if the Change Request is accepted or rejected. + +:need:`Committer ` checks finally if the Change Request is completed and the +required verification measures are executed and sucessfully passed. + +If ``approved``, the status of the concerned PRs change to ``MERGED``, +otherwise, if rejected, PR status changes to ``CLOSED``. + +If ``approved`` the status of the ISSUE is ``CLOSED``. This is also the case for rejected Change +Requests. + + +The figure below shows the workflow for a complex case of a Change Request. + +The ISSUE is linked to SUB-ISSUES, and each SUB-ISSUE is linked to a PR. In principle the Change +Request workflows applies for all SUB-ISSUEs independently. Finally the ISSUE must be closed +manually. + +.. figure:: _assets/score_change_request_workflow_complex_1.drawio.svg + :width: 100% + :align: center + :alt: Change Request Complex Workflow Overview Case 1 + + Change Request Complex Workflow Overview Case 1 + +The figure below shows the workflow for another complex case of a Change Request. + +Here the Change Request has an impact on work products in different repositories, e.g. the +**S-CORE** repository, contains feature work products and a Module repository, contains +Component work products. +The ISSUE is linked to SUB-ISSUES in the **S-CORE** repository, and the SUB-ISSUE is linked to a PR. +But in addition the ISSUE is now linked to another ISSUE in the Module repository, also linked +to a PR. In principle the Change Request workflows applies for all SUB-ISSUEs, ISSUES in +Module repository independently. Finally the ISSUE in the **S-CORE** repository must be closed +manually. + +.. figure:: _assets/score_change_request_workflow_complex_2.drawio.svg + :width: 100% + :align: center + :alt: Change Request Complex Workflow Overview Case 2 + + Change Request Complex Workflow Overview Case 2 + +Change Management SW Platform Work Products +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. list-table:: SW Platform work products + :header-rows: 1 + + * - work product Id + - Link to process + - Process status + - Link to issue + - Link to WP + - WP status + + * - :need:`wp__issue_track_system` + - :doc:`index` + - :ndf:`copy('status', need_id='doc__platform_mgt_plan')` + - n/a + - `Project issues `_ + - established + + * - :need:`wp__platform_mgmt` + - :need:`wf__cr_mt_platform_mngmt_plan` + - :ndf:`copy('status', need_id='wf__cr_mt_platform_mngmt_plan')` + - + - :doc:`index` + - :ndf:`copy('status', need_id='doc__platform_mgt_plan')` + + * - :need:`wp__process_definition` + - :need:`wf__def_app_process_definition` + - :ndf:`copy('status', need_id='wf__def_app_process_definition')` + - `Process community issues `_ + - :ref:`process_description` + - diff --git a/docs/process/index.rst b/docs/process/index.rst index 6002b18cbde..72de57be8a5 100644 --- a/docs/process/index.rst +++ b/docs/process/index.rst @@ -37,7 +37,7 @@ Workflow activities are supported by guidances. General Concepts ~~~~~~~~~~~~~~~~ -General concepts as Lifecycle, Definition of Building Blocks, Traceability can be found here: +General concepts like traceability of work products, life cycle model, buidling blocks can be found here: .. toctree:: :maxdepth: 1 diff --git a/docs/process/process_areas/change_management/change_management_concept.rst b/docs/process/process_areas/change_management/change_management_concept.rst new file mode 100644 index 00000000000..d35dbe8e992 --- /dev/null +++ b/docs/process/process_areas/change_management/change_management_concept.rst @@ -0,0 +1,195 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Concept Description +################### + +.. doc_concept:: Concept Description + :id: doc_concept__change__process + :status: valid + :tags: change_management + +In this section a concept for the Change Management will be discussed. Inputs for this concepts +are both the requirements of ISO26262 Part-8 and ASPICE Requirements from SUP.10 additionally +including the requirements of the different stakeholders for the Change Management process. + +Key concept +*********** +A Change Request is the **ONLY** way to contribute (compare :need:`gd_guidl__contr_request_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 a new Components or +to modify the scope of existing Components. +As a Software Module isd defined as the top-level Component, all statements here for Components +are also valid for Software Modules. + +Inputs +****** + +#. Stakeholders for the Change Requests? +#. Who needs which information? +#. Which Change Requests types can we derive from that? +#. Which attributes are required? +#. How do the different Change Requests types correlate to each other? + +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. + +#. :need:`Committer ` + + * Verifies that the contribution fulfills the **S-CORE** policies + * Approves the contribution + +Standard Requirements +===================== + +Also requirements of standards need to be taken into consideration: + +* ISO 26262 +* 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 producs affected by the Change Request + * - Milestone + - Planned date (milestone) of deployment of the Change Request + + +.. _chm_analysis: + +Analysis of the 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 realisation must be evaluated. +Verifcation measures must be defined. +Use therefore the : :ref:`Impact Analysis Template `. + + +.. _chm_evaluation: + +Evaluation of the Change Request +******************************** + +Based on the analysis results decision about the acceptance, rejection or delay must be taken +by authorized persons. + +Authorized person includes + +#. :need:`Technical Lead ` +#. :need:`Module Lead ` +#. :need:`Safety Manager ` +#. :need:`Security Manager ` +#. :need:`Quality Manager ` + +Further prioritization must be done, e.g. based on release planning. + + +.. _chm_implementation: + +Implementation of the Change Request +************************************ +If the Change Request is accepted, it must be implemented. + + +.. _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 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_traceability: + +Traceability Concept for Change Requests +**************************************** + +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/docs/process/process_areas/change_management/change_management_getstrt.rst b/docs/process/process_areas/change_management/change_management_getstrt.rst new file mode 100644 index 00000000000..0552ff1e4df --- /dev/null +++ b/docs/process/process_areas/change_management/change_management_getstrt.rst @@ -0,0 +1,28 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Getting Started +############### + +.. doc_getstrt:: Getting Started on Change Management + :id: doc_getstrt__change__process + :status: valid + :tags: change_management + +In case you want to contribute a change to **S-CORE** consider to: + +* 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 :ref:`Platform Management Plan `, here especially with :need:`Change Management Plan ` diff --git a/docs/process/process_areas/change_management/change_management_roles.rst b/docs/process/process_areas/change_management/change_management_roles.rst new file mode 100644 index 00000000000..85cebaee83f --- /dev/null +++ b/docs/process/process_areas/change_management/change_management_roles.rst @@ -0,0 +1,32 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Roles +##### + +For change management no additional roles need to be defined. + +Contributing Roles: + + * :need:`Contributor ` + * :need:`Committer ` + * :need:`Contributor ` + * :need:`Module Project Lead ` + * :need:`Safety Manager ` + * :need:`Security Manager ` + * :need:`Quality Manager ` + +A detailed overview of the responsibility for the steps of the requirement process is listed here: + +:ref:`workflow_chm_requirements` diff --git a/docs/process/process_areas/change_management/change_management_workflow.rst b/docs/process/process_areas/change_management/change_management_workflow.rst new file mode 100644 index 00000000000..43b47f71460 --- /dev/null +++ b/docs/process/process_areas/change_management/change_management_workflow.rst @@ -0,0 +1,64 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +Workflow Change Management +########################## + +.. workflow:: Create/Analyse Change Request + :id: wf__change__cr_an_change_request + :status: valid + :tags: change_management + :responsible: rl__contributor + :approved_by: rl__committer + :supported_by: rl__technical_lead, rl__module_lead + :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__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 analysed. + + 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. + + All affeted work products are traced. + + 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:: Review/Approve Change Request + :id: wf__change__rv_ap_change_request + :status: valid + :tags: change_management + :responsible: rl__committer + :approved_by: rl__technical_lead, rl__module_lead + :supported_by: 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__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 implemented and verified. The defined verification measures must be + available and pass. + + The final approval is done by the [Technical Lead (rl__technical_lead)] or the + [Module Project Lead (rl__module_lead)] dependent on the scope. + + The possible outcome is either a Change Request with status “accepted” or “rejected” or kept + "in review". diff --git a/docs/process/process_areas/change_management/change_management_workproducts.rst b/docs/process/process_areas/change_management/change_management_workproducts.rst new file mode 100644 index 00000000000..2b738cd31c1 --- /dev/null +++ b/docs/process/process_areas/change_management/change_management_workproducts.rst @@ -0,0 +1,55 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Work Products Change Management +############################### + +.. workproduct:: Issue tracking system + :id: wp__issue_track_system + :status: valid + :tags: change_management + + | - Change request + | - Change request plan + | - Change report + | - Identified safety anomaly report + | - Impact analysis + | + | 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. + +.. workproduct:: Feature Request + :id: wp__feat_request + :status: valid + :tags: 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, + | which changes the scope of the feature. + +.. workproduct:: Component Request + :id: wp__cmpt_request + :status: valid + :tags: 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, + | which changes the scope of the component. + | Software Modules are also Components (top-level coponent). + +.. needextend:: "docs/process/change_management" in docname + :+tags: change_management diff --git a/docs/process/process_areas/change_management/guidance/change_management_checklist.rst b/docs/process/process_areas/change_management/guidance/change_management_checklist.rst new file mode 100644 index 00000000000..418d1863022 --- /dev/null +++ b/docs/process/process_areas/change_management/guidance/change_management_checklist.rst @@ -0,0 +1,81 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _chm_checklist: + +Checklists +########## + +.. gd_chklst:: Change Request Review Checklist + :id: gd_chklst__change__cr_review + :status: valid + :tags: change_management + :complies: std_req__aspice_40__SUP-10-BP1, std_req__aspice_40__SUP-10-BP3, std_req__aspice_40__SUP-10-BP5 + + | **1. Purpose** + | The purpose of this checklist is to collect the topics to be checked during a Change Request from any contributor. + | It will not be filled out but considered during the review of the Change Request. + | + | **2. Checklist** + | + + .. list-table:: Feature/Component Request Review Checklist + :header-rows: 1 + :widths: 10,30,6 + + * - Id + - Topic + - Status [FAIL|PASS] + * - 1 + - Does the Feature/Component Request follow the template? + - + + * - 2 + - Are all required topics of the Feature/Component Request template filled? + - + + * - 3 + - Does the Change Request has a UID as specified? + - + + * - 4 + - Does the Change Request has a title as specified? + - + + * - 5 + - Does the Change Request has a description as specified? + - + + * - 6 + - Does the Change Request has a impact anaylsis as specified? + - + + * - 7 + - Does the Change Request has a correct safety, security level as specified? + - + + * - 8 + - Does the Change Request has a correct type as specified? + - + + * - 9 + - Does the Change Request has a links to affected work product as specified? + - + + * - 10 + - Does the Change Request has a milestone as specified? + - + * - 11 + - Does the Change Request has verification measure as specified? + - diff --git a/docs/process/process_areas/change_management/guidance/change_management_component_template.rst b/docs/process/process_areas/change_management/guidance/change_management_component_template.rst new file mode 100644 index 00000000000..88864a1f0a8 --- /dev/null +++ b/docs/process/process_areas/change_management/guidance/change_management_component_template.rst @@ -0,0 +1,165 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _chm_component_templates: + +Component Template +================== + +.. gd_temp:: Component Request Template + :id: gd_temp__change__component_request + :status: valid + :complies: std_req__aspice_40__SUP-10-BP1, std_req__aspice_40__SUP-10-BP2, std_req__aspice_40__SUP-10-BP3, std_req__aspice_40__SUP-10-BP5, std_req__iso26262__support_21, std_req__iso26262__support_22, , std_req__iso26262__support_23 + +.. attention:: + Remove everything above when copying and filling the template. + +[Your Component Name] +--------------------- + +.. note:: Document header + +.. document:: [Your Feature Name] + :id: doc__change__component_name + :status: draft + :safety: ASIL_B + :tags: change_management + +.. attention:: + The above directive must be updated according to your Component. + + - Modify ``name`` to be your Component Name + - Modify ``id`` to be your Component Name in upper snake case preceded by ``DOC_`` + - Adjust ``status`` to be ``valid`` + - Adjust ``asil`` according to your needs + +Abstract +-------- + +[A short (~200 word) description of the contribution being addressed.] + + +Motivation +---------- + +[Clearly explain why the existing platform/project solution is inadequate to address the topic that the CR solves.] + + .. note:: + The motivation is critical for CRs that want to change the existing components. + It should clearly explain why the existing solution is inadequate to address the topic that the CR solves. + 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. + + +Specification +------------- + +[Describe the requirements, architecture of any new component.] or +[Describe the change to requirements, architecture, implementation, documentation of any change request.] + + .. note:: + A CR shall specify the component requirements as part of our platform/project. + Thereby the :need:`rl__module_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 component?] + + .. 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. + Link here to the filled out :need:`Impact Analysis Template ` or copy the template in this chapter. + + +Safety Impact +------------- + +[How could the safety be impacted by the new/modified component?] + + .. 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 ` or copy the template in this chapter. + +[What is the expected ASIL level?] +[What is the expected classification of the contribution?] + + .. note:: + Use the component classification method here to classfiy your component, if it shall to be used in a safety context: :need:`gd_temp__component_classification`. + + + +License Impact +-------------- + +[How could the copyright impacted by the license of the new contribution?] + + +How to Teach This +----------------- + +[How to teach users, new and experienced, how to apply the CR to their work.] + + .. note:: + For a CR that adds new functionality or changes behavior, 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 +--------- + +[A collection of footnotes cited in the CR, and a place to list non-inline hyperlink targets.] diff --git a/docs/process/process_areas/change_management/guidance/change_management_feature_template.rst b/docs/process/process_areas/change_management/guidance/change_management_feature_template.rst new file mode 100644 index 00000000000..01ccdbf07bf --- /dev/null +++ b/docs/process/process_areas/change_management/guidance/change_management_feature_template.rst @@ -0,0 +1,176 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _chm_feature_templates: + +Feature Template +================ + +.. gd_temp:: Feature Request Template + :id: gd_temp__change__feature_request + :status: valid + :complies: std_req__aspice_40__SUP-10-BP1, std_req__aspice_40__SUP-10-BP2, std_req__aspice_40__SUP-10-BP3, std_req__aspice_40__SUP-10-BP5, std_req__iso26262__support_21, std_req__iso26262__support_22, , std_req__iso26262__support_23 + +.. attention:: + Remove everything above when copying and filling the template. + +[Your Feature Name] +------------------- + +.. note:: Document header + +.. document:: [Your Feature Name] + :id: doc__change__feature_name + :status: draft + :safety: ASIL_B + :tags: change_management + +.. attention:: + The above directive must be updated according to your Feature. + + - Modify ``name`` to be your Feature Name + - Modify ``id`` to be your Feature Name in upper snake case preceded by ``DOC_`` + - Adjust ``status`` to be ``valid`` + - Adjust ``asil`` according to your needs + +Feature flag +------------ + +To activate this feature, use the following feature flag: + +``experimental_[your_feature_name]`` + + .. note:: + The feature flag must reflect the feature name in snake_case. Further, it is prepended with ``experimental_``, as + long as the feature is not yet stable. + +Abstract +-------- + +[A short (~200 word) description of the contribution being addressed.] + + +Motivation +---------- + +[Clearly explain why the existing platform/project solution is inadequate to address the topic that the CR solves.] + + .. note:: + The motivation is critical for CRs that want to change the existing features or infrastructure. + It should clearly explain why the existing solution is inadequate to address the topic that the CR solves. + 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. + + +Specification +------------- + +[Describe the requirements, architecture of any new feature.] or +[Describe the change to requirements, architecture, implementation, process, documentation, infrastructure of any change request.] + + .. note:: + A CR shall specify the stakeholder requirements as part of our platform/project. + Thereby the :need:`rl__technical_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. + Link here to the filled out :need:`Impact Analysis Template ` or copy the template in this chapter. + + +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 ` or copy the template in this chapter. + +[What is the expected ASIL level?] +[What is the expected classification of the contribution?] + + .. note:: + Use the component classification method here to classfiy your component, if it shall to be used in a safety context: :need:`gd_temp__component_classification`. + + + +License Impact +-------------- + +[How could the copyright impacted by the license of the new contribution?] + + +How to Teach This +----------------- + +[How to teach users, new and experienced, how to apply the CR to their work.] + + .. note:: + For a CR that adds new functionality or changes behavior, 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 +--------- + +[A collection of footnotes cited in the CR, and a place to list non-inline hyperlink targets.] diff --git a/docs/process/process_areas/change_management/guidance/change_management_guideline.rst b/docs/process/process_areas/change_management/guidance/change_management_guideline.rst new file mode 100644 index 00000000000..2220de632c6 --- /dev/null +++ b/docs/process/process_areas/change_management/guidance/change_management_guideline.rst @@ -0,0 +1,173 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Guidelines +########## + +.. gd_guidl:: Change Request Guideline + :id: gd_guidl__change__change_request + :status: valid + :complies: std_req__iso26262__support_19, std_req__iso26262__support_23, std_req__iso26262__support_25, std_req__iso26262__support_23, std_req__iso26262__support_26 + +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 desribed in the :need:`[[title]]`. + +Templates +--------- + +*Need* templates displaying the correct syntax and attribute definition are provided for each +Change Request type. + +.. 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 +---------- + +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 type == "gd_req" + :style: table + :columns: title + :colwidths: 30 + + +* ID: Unique integer number +* For the remaining attributes only predefined values can be used. A more detailed description can + be found here: :ref:`chm_attributes` + + +.. _workflow_chm_requirements: + +Workflow for Change Requests +============================ + +This section describes in detail which steps need to be performed for a Change Request. + +.. list-table:: Workflow for Change Request + :header-rows: 1 + :widths: 10,60,30 + + * - Step + - Description + - Responsible + * - :ref:`1. ` + - Create change request + - :need:`[[title]] ` + * - :ref:`2. ` + - Analyse Change Request + - :need:`[[title]] ` + * - :ref:`3. ` + - Approve Change Request + - :need:`[[title]] ` + * - :ref:`4. ` + - Implement Change Request + - :need:`[[title]] ` + * - :ref:`5. ` + - Verify Change Request + - :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 tpye (new feature/component request or +feature/component modification). + +The desription 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_analyse_change_request: + +Analyse Change Request +---------------------- + +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: + +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 producst and on functional safety, security +5. Define verification measures used to confirm the implementation + +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. + +.. _chm_approve_change_request: + +Approve Change Request +---------------------- + +: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". + +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_implement_change_request: + +Implement Change Request +------------------------ + +:need:`[[title]] ` implements the Change Request. This is indicated by the +Change Request status "in implementation". 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 traceability from the Change Request to the affected work products must be established +during implementation. +Also the verification measures must be executed. + +.. _chm_verify_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 confirmed. + +The Change Request is closed by setting the status to "confirmed". diff --git a/docs/process/process_areas/change_management/guidance/change_management_impact_analysis_template.rst b/docs/process/process_areas/change_management/guidance/change_management_impact_analysis_template.rst new file mode 100644 index 00000000000..e1d21453811 --- /dev/null +++ b/docs/process/process_areas/change_management/guidance/change_management_impact_analysis_template.rst @@ -0,0 +1,112 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _chm_impact_analysis_templates: + +Impact Analysis Template +======================== + +.. gd_temp:: Impact Analysis Template + :id: gd_temp__change__impact_analysis + :status: valid + :complies: std_req__aspice_40__SUP-10-BP2, std_req__iso26262__support_22, , std_req__iso26262__support_23 + +[will be updated by improvement issue: #621] + +Type of Change Request +---------------------- + +[New Feature/Component, Modification of an existing Feature/Component] + +Dependenices on other Change Requests +------------------------------------- + +[List all dependencies on other Change Request] + +Affected Work Products +---------------------- + +[List all work products and elements affected by the Change Request] + + .. note:: + For the identification of the affected work products use the Traceability Analysis approach. + Traceability analysis uses the exsiting links between different elments (requirements, architecture, implementation, etc.) + for the identification of the affectted work products and elements. + +Work Products to be changed +--------------------------- + +[List all work products and elements to be modified by the Change Request] + + .. note:: + Use the results from the Traceability Analysis approach. + + +Stakeholder identification +-------------------------- + +[Describe here which stakeholder and which roles of the stakeholder are invovled to execute the Change Request] + + + .. note:: + Typically the :need:`Technical Project Leads ` or :need:`Module Leads ` are involved + for planning and approval activities. As well as :need:`Safety Manager ` or :need:`Security Manager ` + are resonsible for Change Request which has impact on functional safety or security. + +Schedule for realisation and verification of the Change Request +--------------------------------------------------------------- + +[Describe here which Milestones are considered to realize the Change Request.] +[Describe here which work products to be changed.] +[Describe here the verification methods used for the changed work products] + + .. note:: + A draft realization plan may support the realisation proposal. + +Potential Impact on Security +----------------------------- + +[How could a malicious user take advantage of this new/modified feature/component?] + +Which security requirements are affected or has to be changed? +Could the new/modified feature/component enable new threat scenarios? +Could the new/modified feature/component enable new attack pathes? +Could the new/modified feature/component impact functional safety? +If applicable, which additional security measures must be implemented to mitigate the risk. + + .. note:: + Use Trust Bondary, Defence in Depth Analysis and/or Security Software Critically Analysis, + Vulnerability Analysis. + [Methods will be defined later in Process area Security Analysis] + +Potential Impact on Safety +-------------------------- + +[How could the safety be impacted by the new/modified feature/component?] + +Which safety requirements are affected or has to be changed? +Could the new/modified feature/component 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] + +For new feature/component contributions: + +[What is the expected ASIL level?] +[What is the expected classification of the contribution?] + + .. note:: + Use the component classification method here to classfiy your component, if it shall to be used in a safety context: :need:`gd_temp__component_classification`. diff --git a/docs/process/process_areas/change_management/guidance/change_management_reqs.rst b/docs/process/process_areas/change_management/guidance/change_management_reqs.rst new file mode 100644 index 00000000000..e31cf3c9cda --- /dev/null +++ b/docs/process/process_areas/change_management/guidance/change_management_reqs.rst @@ -0,0 +1,160 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _chm_process_requirements: + +Process Requirements +==================== + +.. _chm_process_change_request_attributes: + +Change Request Attributes +------------------------- + +.. gd_req:: Change Request attribute: UID + :id: gd_req__change__attr_uid + :status: valid + :tags: attribute,mandatory + :satisfies: wf__change__cr_an_change_request, wf__change__rv_ap_change_request + :complies: std_req__aspice_40__SUP-10-BP1, std_req__iso26262__support_16, std_req__iso26262__support_20, std_req__iso26262__support_23, std_req__iso26262__support_28 + + Each Change Request shall have a unique ID. It shall be in an integer number. + +.. gd_req:: Requirement attribute: status + :id: gd_req__change__attr_status + :status: valid + :tags: attribute, mandatory + :satisfies: wf__change__cr_an_change_request, wf__change__rv_ap_change_request + :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_16, std_req__iso26262__support_21, std_req__iso26262__support_23, std_req__iso26262__support_25 + + Each Change Request shall have a status: + + * draft + * in review + * accepted + * rejected + +.. gd_req:: Change Request attribute: title + :id: gd_req__change__attr_title + :status: valid + :tags: attribute, mandatory + :satisfies: wf__change__cr_an_change_request, wf__change__rv_ap_change_request + :complies: std_req__aspice_40__SUP-10-BP1, std_req__iso26262__support_16, std_req__iso26262__support_21 + + Reason for the Change Request + +.. gd_req:: Change Request attribute: description + :id: gd_req__change__attr_impact_description + :status: valid + :tags: attribute, mandatory + :satisfies: wf__change__cr_an_change_request, wf__change__rv_ap_change_request + :complies: std_req__aspice_40__SUP-10-BP2, std_req__iso26262__support_16, std_req__iso26262__support_21, std_req__iso26262__support_22, std_req__iso26262__support_23, std_req__iso26262__support_27, std_req__iso26262__support_28 + + Exact description of the Change Request, including impact analysis on functional safety, + security, implementation (schedule, risks, resources) verifcation (measures defined). + +.. gd_req:: Change Request attribute: safety + :id: gd_req__change__attr_impact_safety + :status: valid + :tags: attribute, mandatory + :satisfies: wf__change__cr_an_change_request, wf__change__rv_ap_change_request + :complies: std_req__aspice_40__SUP-10-BP2, std_req__iso26262__support_21 + + Each Change Request shall have a automotive safety integrity level (ASIL) identifier: + + * QM + * ASIL_B + * ASIL_D + +.. gd_req:: Change Request attribute: security + :id: gd_req__change__attr_impact_security + :status: valid + :tags: attribute, mandatory + :satisfies: wf__change__cr_an_change_request, wf__change__rv_ap_change_request + :complies: std_req__aspice_40__SUP-10-BP2, std_req__iso26262__support_21 + + Each Change Request shall have a security relevance identifier: + + * Yes + * No + +.. gd_req:: Change Request: Types + :id: gd_req__change__types + :status: valid + :tags: structure + :satisfies: wf__change__cr_an_change_request, wf__change__rv_ap_change_request + :complies: std_req__aspice_40__SUP-10-BP1 + + * Feature + * Feature Modification + * Component + * Componnent Modification + + Feature/Component means new Feature/Component + +.. gd_req:: Change Request attribute: Affected Work Products + :id: gd_req__change__attr_affected_wp + :status: valid + :tags: attribute, mandatory + :satisfies: wf__change__cr_an_change_request, wf__change__rv_ap_change_request + :complies: std_req__aspice_40__SUP-10-BP4, std_req__iso26262__support_17, std_req__iso26262__support_21, std_req__iso26262__support_27, std_req__iso26262__support_28 + + Links to the work producs affected by the Change Request + +.. gd_req:: Change Request attribute: Milestone + :id: gd_req__change__attr_milestone + :status: valid + :tags: attribute, mandatory + :satisfies: wf__change__cr_an_change_request, wf__change__rv_ap_change_request + :complies: std_req__aspice_40__SUP-10-BP6, std_req__iso26262__support_18 + + Milestone unitl the Change Requeste must be implemented (used for prioritization) +.. _chm_process_change requests_checks: + + +Change Request Checks +''''''''''''''''''''' + +.. gd_req:: Change Requests mandatory attributes provided + :id: gd_req__change_attr_mandatory + :status: valid + :tags: attribute, check + :satisfies: wf__change__cr_an_change_request, wf__change__rv_ap_change_request + :complies: + + It shall be checked if all mandatory attributes for each Change Request + is provided by the user. For all requirements following attributes shall be mandatory: + + .. needtable:: Overview mandatory change request attributes + :filter: "mandatory" in tags and "attribute" in tags and type == "gd_req" + :style: table + :columns: title + :colwidths: 30 + + +Change Request Traceability Impact Analysis Tool +'''''''''''''''''''''''''''''''''''''''''''''''' + +.. gd_req:: Change Requests Impact Analysis Tool + :id: gd_req__change_tool_impact_analysis + :status: valid + :tags: check, tool + :satisfies: wf__change__cr_an_change_request, wf__change__rv_ap_change_request + :complies: + + It shall be reported, which work products and elements are affected by adding a new + feature or component or by a modification of an existing feature or component. + +.. needextend:: "process_areas/change_management" in docname + :+tags: change_management diff --git a/docs/process/process_areas/change_management/guidance/index.rst b/docs/process/process_areas/change_management/guidance/index.rst new file mode 100644 index 00000000000..fb114779084 --- /dev/null +++ b/docs/process/process_areas/change_management/guidance/index.rst @@ -0,0 +1,26 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Guidance +######## + +.. toctree:: + :maxdepth: 1 + + change_management_guideline + change_management_checklist + change_management_feature_template + change_management_component_template + change_management_impact_analysis_template + change_management_reqs diff --git a/docs/process/process_areas/change_management/index.rst b/docs/process/process_areas/change_management/index.rst new file mode 100644 index 00000000000..0d1d81c41bc --- /dev/null +++ b/docs/process/process_areas/change_management/index.rst @@ -0,0 +1,29 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +.. _change_management: + +Change Management +################# + +.. toctree:: + :maxdepth: 1 + + + change_management_getstrt + change_management_concept + guidance/index + change_management_roles + change_management_workflow + change_management_workproducts diff --git a/docs/process/process_areas/index.rst b/docs/process/process_areas/index.rst index 4821d259b48..f7ef27b7fca 100644 --- a/docs/process/process_areas/index.rst +++ b/docs/process/process_areas/index.rst @@ -19,7 +19,8 @@ Process Areas :maxdepth: 1 :glob: - architecture_design/index.rst + change_management/index.rst documentation_management/index.rst - requirements_engineering/index.rst safety_management/index.rst + requirements_engineering/index.rst + architecture_design/index.rst diff --git a/docs/process/process_areas/safety_management/guidance/template_feature_safety_wp.rst b/docs/process/process_areas/safety_management/guidance/template_feature_safety_wp.rst index 3cd41485dcf..d38ea5baacc 100644 --- a/docs/process/process_areas/safety_management/guidance/template_feature_safety_wp.rst +++ b/docs/process/process_areas/safety_management/guidance/template_feature_safety_wp.rst @@ -32,7 +32,7 @@ Feature Safety Work Products Template - WP status * - :need:`wp__feat_request` - - :ref:`feature_request_template` + - :ref:`Feature Request Template ` - - - diff --git a/docs/process/workproducts/index.rst b/docs/process/workproducts/index.rst index b8f20ea8b62..4b805f7d3f6 100644 --- a/docs/process/workproducts/index.rst +++ b/docs/process/workproducts/index.rst @@ -64,28 +64,6 @@ General | * Identifies the associated quality criteria | * Identifies any associated measurements using the information -.. workproduct:: Issue tracking system - :id: wp__issue_track_system - :status: draft - :tags: requirements_management, safety_management - - | - Identified safety anomaly reports - | - Change requests (= Contribution Request) - | - Impact analysis - | - change request plan - | - Change report - | - | Safety anomaly: Conditions that deviate from expectations and that can lead to harm. - | The documentation of a change shall contain the list of changed work products, the details of the change and the planned date of deployment of the change. - -.. workproduct:: Feature Request - :id: wp__feat_request - :status: draft - :tags: contribution_management, safety_management - - | - Feature request - | - Change request - .. workproduct:: Platform Management Plan :id: wp__platform_mgmt :status: valid