diff --git a/process/folder_templates/index.rst b/process/folder_templates/index.rst index dee37b0e11..1ede88c580 100644 --- a/process/folder_templates/index.rst +++ b/process/folder_templates/index.rst @@ -12,6 +12,8 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +.. _folder_templates: + Folder Templates ################ diff --git a/process/process_areas/configuration_management/configuration_concept.rst b/process/process_areas/configuration_management/configuration_concept.rst new file mode 100644 index 0000000000..9bf0deb815 --- /dev/null +++ b/process/process_areas/configuration_management/configuration_concept.rst @@ -0,0 +1,53 @@ +.. + # ******************************************************************************* + # 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 +------- + +.. doc_concept:: Configuration Management Concept + :id: doc_concept__configuration__process + :status: valid + +In this section a concept for the configuration management will be discussed. +Inputs for this concepts are mainly the requirements of ISO26262 "Part 8: Supporting Processes" +and ASPICE Requirements from PAM4.0, SUP.8 + +Key concept +^^^^^^^^^^^ +The Configuration Management Plan should define the strategy to manage the configuration items +in an effective and repeatable way for the project life cycle. + +Note: configuration items are all defined work products in the project plus additional arefacts not developed by the project +needed for the building of the binaries, documentation and verification reports (e.g. tools, external SW libraries). + +Inputs +^^^^^^ + +#. Stakeholders for the configuration process work products? +#. Who needs which information? +#. Which configuration items do we have? +#. What tooling do we need? + +Stakeholders +^^^^^^^^^^^^ + +#. :need:`Technical Lead ` + + * for creating a module or a platform release a baseline of all configuration items is needed + +#. :need:`Contributor ` and :need:`Committer ` + + * wants know which work products's version has to be used as input for his work + * wants to share their created work product with others for example to get those reviewed + * wants to integrate their created work product with other work products diff --git a/process/process_areas/configuration_management/configuration_getstrt.rst b/process/process_areas/configuration_management/configuration_getstrt.rst new file mode 100644 index 0000000000..838ac651f8 --- /dev/null +++ b/process/process_areas/configuration_management/configuration_getstrt.rst @@ -0,0 +1,30 @@ +.. + # ******************************************************************************* + # Copyright (c) 2025 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Getting Started +############### + +.. doc_getstrt:: Configuration Management Get Started + :id: doc_getstrt__configuration__process + :status: valid + +In case you are appointed as a :need:`Technical Lead ` by the :need:`rl__project_lead` in the project: + +* On platform level, process community provides a draft configuration management plan, + based on the template :need:`gd_temp__config_mgt_plan`, just set it to "valid" +* On module level, follow the configuration management plan of the platform also in your module. + If the configuration management plan needs updating for your module, the same template can be used. + +As a normal contributor or committer consult the configuration management plan, it should +be mainly your task to use the project's selected version management tool. diff --git a/process/process_areas/configuration_management/configuration_roles.rst b/process/process_areas/configuration_management/configuration_roles.rst new file mode 100644 index 0000000000..de5cf09bfa --- /dev/null +++ b/process/process_areas/configuration_management/configuration_roles.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 + # ******************************************************************************* + +Roles +##### + +For configuration management no additional roles need to be defined. + +Contributing Roles: + + * :need:`Contributor ` + * :need:`Committer ` + * :need:`Technical Lead ` + * :need:`Module Project Lead ` + +A detailed overview of the responsibility for the steps of the configuration management is listed here: + +:need:`wf__platform__cr_mt_platform_mgmt_plan` diff --git a/process/process_areas/configuration_management/configuration_workflow.rst b/process/process_areas/configuration_management/configuration_workflow.rst new file mode 100644 index 0000000000..bfbbb70da7 --- /dev/null +++ b/process/process_areas/configuration_management/configuration_workflow.rst @@ -0,0 +1,24 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + + +Workflows Configuration Management +################################## + +The main work product is the configuration management plan, which is a part of the platform management plan. +Thus the work flow :need:`wf__platform__cr_mt_platform_mgmt_plan` applies. + +Baselines (sets of configuration items and their versions) defining a SW Release on platform or module level +are created as part of this process but are documented in the respective release notes. +This is part of workflows :need:`wf__rel__mod_rel_note` and :need:`wf__rel__platform_rel_note` diff --git a/process/process_areas/configuration_management/configuration_workproducts.rst b/process/process_areas/configuration_management/configuration_workproducts.rst new file mode 100644 index 0000000000..b6466de900 --- /dev/null +++ b/process/process_areas/configuration_management/configuration_workproducts.rst @@ -0,0 +1,24 @@ +.. + # ******************************************************************************* + # 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 Configuration Management +###################################### + +.. workproduct:: Platform Configuration Management Plan + :id: wp__config_mgt_plan + :status: valid + :tags: config_management + :complies: std_wp__iso26262__support_751 + + Config Management Plan (Part of the Platform Management Plan, :need:`wp__platform_mgmt`) diff --git a/process/process_areas/configuration_management/guidance/process_req.rst b/process/process_areas/configuration_management/guidance/configuration_process_req.rst similarity index 88% rename from process/process_areas/configuration_management/guidance/process_req.rst rename to process/process_areas/configuration_management/guidance/configuration_process_req.rst index 7079dfa5e3..789e958205 100644 --- a/process/process_areas/configuration_management/guidance/process_req.rst +++ b/process/process_areas/configuration_management/guidance/configuration_process_req.rst @@ -15,6 +15,14 @@ Configuration Management Process Requirements ============================================= +.. gd_req:: Unique Id + :id: gd_req__configuration_uid + :status: valid + :tags: done_automation, config_mgt + :complies: std_req__iso26262__support_745, std_req__aspice_40__SUP-8-BP8 + + The structured text tool shall check that the Id's of the configuration items are unique. + .. gd_req:: Permanent Storage :id: gd_req__config__workproducts_storage :status: valid diff --git a/process/process_areas/configuration_management/guidance/configuration_templates.rst b/process/process_areas/configuration_management/guidance/configuration_templates.rst new file mode 100644 index 0000000000..f8b4fd86bd --- /dev/null +++ b/process/process_areas/configuration_management/guidance/configuration_templates.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 + # ******************************************************************************* + +.. _configuration_templates: + +Template Configuration Management Plan +====================================== + +.. gd_temp:: Configuration Management Plan Template + :id: gd_temp__config_mgt_plan + :status: valid + :complies: std_req__iso26262__support_741, std_req__iso26262__support_742, std_req__iso26262__support_743, std_req__iso26262__support_744, std_req__iso26262__support_745, std_req__aspice_40__SUP-8-BP1, std_req__aspice_40__SUP-8-BP2, std_req__aspice_40__SUP-8-BP3, std_req__aspice_40__SUP-8-BP4, std_req__aspice_40__SUP-8-BP5, std_req__aspice_40__SUP-8-BP8, std_req__aspice_40__iic-13-08 + +Purpose ++++++++ + +The Configuration Management Plan defines how the integrity of all work products +and other project relevant artefacts can be reached and maintained. + + +Objectives and scope +++++++++++++++++++++ + +Goal of this plan is to describe + +* how all configuration items in the project are identified +* the infrastructure to store the configuration items +* how to make all configuration items available to all concerned parties +* where to find which configuration item +* how to retrieve specific versions of a configuration item +* how to modify a configuration item and how to control this +* how to create and store versions of configuration items +* how to manage baselines +* how to backup and recover (including long term storage) +* how to report the configuration status + +note: for definition of "configuration items" check :need:`doc_concept__configuration__process` + + +Approach +++++++++ + +The steps below describe how configuration identification, retrieval, modification, branches and baselines, backup and recovery are organized. + +Lifecycle +^^^^^^^^^ + +The configuration management of the project is in place during the complete development lifecycle as described in :ref:`general_concepts_lifecycle`. +I.e. in Concept Phase, Development Phase and Maintenance. + +Identification and Properties +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This should cover :need:`std_req__aspice_40__SUP-8-BP1` and :need:`std_req__aspice_40__SUP-8-BP2`. + +Each work product is identified by its "Docs-as-Code" Id, this includes documents identified as such (by the document header as defined in :need:`gd_temp__documentation`). +The complete list of project documents is defined in the project's . +Ids are checked for uniqueness, see :need:`gd_req__configuration_uid`. +"Docs-as-Code" is also used to document the work products properties/attributes defined in the process area descriptions. +The work products are stored in text or code files (these are identified by their filenames) within the selected version management tool. + +For additional artefacts these are either + +- files - are identified by their path/filename +- precompiled tools/binaries - CI build configuration identifies those by their hash. +- (external) tools/binaries to be built in CI - CI build configuration identifies those by their version. + + +Retrieval +^^^^^^^^^ + + +Their content is defined in the process/workproducts and process_area//workproducts files. +To find the location of the work products, the folder structure definition :ref:`folder_templates` can be used. + + +For other artefacts: these are pulled into integration repository by forking to be handled as above. + + +Control and Modification +^^^^^^^^^^^^^^^^^^^^^^^^ + +This should cover :need:`std_req__aspice_40__SUP-8-BP3` and :need:`std_req__aspice_40__SUP-8-BP4` + +Files or new work products contained in these files are created in local branches by the :need:`Contributor ` +and shared for review and incorporation into a main branch, which are after their acceptance merged by the :need:`Committer ` +(this should be supported by version management tool). +The same applies for changes in existing configuration items. +All modifications (differences between before and after) are documented in the pull-requests and are the main input to the pull-request reviews. +See also . + +For tool/binaries modifications (version changes) are controlled by the CI build files. +These build files, like other files, are also maintained in version management tool. + + +Branches and Baselines +^^^^^^^^^^^^^^^^^^^^^^ + +This should cover :need:`std_req__aspice_40__SUP-8-BP5` and :need:`std_req__aspice_40__iic-13-08` + +Branches are used as a means of parallel development. In the project the following types of branches will be used: + +* local branches - created from "remote" branches, in these the development of the contributors takes place, no restriction on naming. +* main branch - a "remote" branch (named "main") which contains all the latest file versions checked by CI, reviewed, accepted and merged. +* release branch - a "remote" branch derived from main branch which is used to prepare a release, + no functional code changes are allowed, only bug fixes and verification based improvements. + Only the technical lead is allowed to approve a merge into a release branch. The branch name is given as defined in :need:`doc_concept__rel__process`. + +The "remote" branch is not "local" to the developer but resides on the "remote" version management server. + +In project all configuration items are kept in the version management tool, this means that there only needs to be one baseline for these +(and not multiple ones for each of the work products which are maintained in seperate tools). + +See also . + +Every change in the release repository is also taken over into the main branch. The module development team +can decide how to ensure this (e.g. by development in main and cherrypick to release branch). + + +Backup and Recovery +^^^^^^^^^^^^^^^^^^^ + +This should cover :need:`std_req__aspice_40__SUP-8-BP8` + + +For the long term storage, additional measures should be taken, see :need:`gd_req__config__workproducts_storage` + +Status and Reporting +^^^^^^^^^^^^^^^^^^^^ + +This should cover :need:`std_req__aspice_40__SUP-8-BP6` and :need:`std_req__aspice_40__SUP-8-BP7` + +Every work product defined in our proceses has a "status" attribute. These are used to communicate to all the stakeholders. +The main communication means is a document list containing all documents and workproducts including their status. +This list is typically part of the Documentation Management Plan as part of the Platform Management Plan, +as defined in :need:`gd_guidl__documentation`. +Completeness of the configuration items (within a baseline) is checked at least for every release +against the list of planned documents and workproducts, which is also part of the Documentation Management Plan. + +Configuration Management Tooling +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Almost all requirements of the standards towards configuration management can be covered by +standard versioning tooling of the Eclipse Foundation and of the project +("Docs-as-Code" identification of work products). +The respective tools used in the project are: + +* versioning tool: +* "Docs-as-Code" tool: +* CI build tool: + +Note 1: A versioning tool covers part of configuration management but not all (namely: storage, retrieval, control and modification, branching and baselining). + +Note 2: A "Docs-as-Code" tool is used to identify, attribute and link parts of text files and generate human and machine readable documentation. diff --git a/process/process_areas/configuration_management/guidance/index.rst b/process/process_areas/configuration_management/guidance/index.rst new file mode 100644 index 0000000000..17a1a3c55d --- /dev/null +++ b/process/process_areas/configuration_management/guidance/index.rst @@ -0,0 +1,22 @@ +.. + # ******************************************************************************* + # 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 + + configuration_templates + configuration_process_req diff --git a/process/process_areas/configuration_management/index.rst b/process/process_areas/configuration_management/index.rst index ada3ab37f5..7df75ef837 100644 --- a/process/process_areas/configuration_management/index.rst +++ b/process/process_areas/configuration_management/index.rst @@ -17,48 +17,6 @@ Configuration Management ======================== -Concept -------- - -.. doc_concept:: Configuration Management Concept - :id: doc_concept__configuration__process - :status: valid - -In this section a concept for the configuration management will be discussed. -Inputs for this concepts are mainly the requirements of ISO26262 "Part 8: Supporting Processes" -and ASPICE Requirements from PAM4.0, SUP.8 - -Inputs -^^^^^^ - -#. Stakeholders for the configuration process work products? -#. Who needs which information? -#. Which work products do we have? -#. What tooling do we need? - -Stakeholders -^^^^^^^^^^^^ - -#. :need:`Technical Lead ` - - * for creating a module or a platform release a baseline of all configuration items is needed - -#. :need:`Contributor ` and :need:`Committer ` - - * wants know which configuration items version has to be used as input for his work - * wants to share their created work product with others for example to get those reviewed - * wants to integrate share their created work product with other work products - -note: configuration items are all defined S-CORE work products plus additional arefacts not produced by S-CORE -needed for the building of the documentation and verification reports (e.g. tools, external SW libraries) - - -Work Products -^^^^^^^^^^^^^ - -`REPLACE_doc__config_mgt_plan` is a document and part of the work product :need:`wp__platform_mgmt`. - - Configuration Management Tooling ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -66,44 +24,14 @@ Almost all requirements of the standards towards configuration management can be standard tooling of the Eclipse Foundation (github for versioning) and of the S-CORE project (sphinx-needs for text based identification of work products). -For the automated storage additional tooling is created (see :doc:`guidance/process_req`) - -Getting started ---------------- - -.. doc_getstrt:: Configuration Management Get Started - :id: doc_getstrt__configuration__process - :status: valid - -In case you are appointed as a :need:`Technical Lead ` by the :need:`rl__project_lead` in the S-CORE project: - -* On platform level, process community already provided a draft configuration management plan, - see `REPLACE_doc__config_mgt_plan`, just set it to "valid" -* On module level, create a configuration management plan using the platform one as a template. - If no configuration management plan on module level is created, the platform one is adopted. - -As a normal contributor or committer consult the `REPLACE_doc__config_mgt_plan`, but this should not -differ from normal usage of github as a configuration management tool. - -Workflows ---------- - -The main work product is the configuration management plan, which is a part of the platform management plan. -Thus the work flow :need:`wf__platform__cr_mt_platform_mgmt_plan` applies. - -Baselines (sets of workproducts and their versions) defining a SW Release on platform or module level -are created as part of this process but are documented in the respective release notes. - -Guidance --------- - -The configuration management guideline is contained within the configuration management plan, -to have all relevant information in one space, see `REPLACE_gd_guidl__configuration` - -Some process requirements to be automated are available: +For the automated storage additional tooling is created (see :doc:`guidance/configuration_process_req`) .. toctree:: :maxdepth: 1 - :glob: - guidance/process_req.rst + configuration_getstrt + configuration_concept + guidance/index + configuration_roles + configuration_workflow + configuration_workproducts diff --git a/process/process_areas/documentation_management/documentation_workproducts.rst b/process/process_areas/documentation_management/documentation_workproducts.rst index 6fdd258e97..8424a94419 100644 --- a/process/process_areas/documentation_management/documentation_workproducts.rst +++ b/process/process_areas/documentation_management/documentation_workproducts.rst @@ -18,13 +18,13 @@ Work Products Documentation Management .. workproduct:: Documentation Management Plan :id: wp__document_mgt_plan :status: valid - :complies: std_wp__iso26262__support_1051, std_wp__iso26262__support_1052 + :complies: std_wp__iso26262__support_1051, std_wp__iso26262__support_1052, std_req__aspice_40__iic-01-52 Document Management Plan (Part of the Platform Management Plan) Defines the documentation strategy which covers the following aspects: - * What is documented where and when? + * What is documented where and when? (Leading to a configuration item list) * How to review, update, (re-)approve documentations? * What is the status of a document and how are changes identified? * How to ensure the avaibility of the documents over time? diff --git a/process/process_areas/documentation_management/guidance/documentation_guideline.rst b/process/process_areas/documentation_management/guidance/documentation_guideline.rst index 57c71728ee..ed29580141 100644 --- a/process/process_areas/documentation_management/guidance/documentation_guideline.rst +++ b/process/process_areas/documentation_management/guidance/documentation_guideline.rst @@ -20,7 +20,9 @@ Guideline :status: valid :complies: std_req__iso26262__support_1041, std_req__iso26262__support_1042, std_req__iso26262__support_1043, std_req__iso26262__support_1044, std_req__iso26262__support_1045, std_req__iso26262__support_1046 -The planning for the documents is part of the Platform Management Plan. +The planning for the documents is part of the :need:`wp__document_mgt_plan` within the Platform Management Plan. +This plan includes the configuration item list containing all work products created in the project +as well as additional artefacts as defined in :need:`doc_concept__configuration__process`. The formal elements for documentations in S-CORE are described here: `REPLACE_doc__documentation_mgt_plan`. diff --git a/process/process_areas/platform_management/platform_management_workflow.rst b/process/process_areas/platform_management/platform_management_workflow.rst index 02f8e60f9f..b947839c84 100644 --- a/process/process_areas/platform_management/platform_management_workflow.rst +++ b/process/process_areas/platform_management/platform_management_workflow.rst @@ -25,7 +25,7 @@ Workflow Platform Management :approved_by: rl__process_community :supported_by: rl__safety_manager, rl__security_manager, rl__quality_manager :input: wp__policies, wp__issue_track_system - :output: wp__platform_mgmt, wp__project_mgt, wp__document_mgt_plan + :output: wp__platform_mgmt, wp__project_mgt, wp__document_mgt_plan, wp__config_mgt_plan :contains: gd_temp__platform__mgmt_plan, gd_guidl__platform__mgmt_plan, gd_guidl__documentation, gd_chklst__documentation__review, gd_temp__documentation :has: doc_concept__platform__process, doc_getstrt__platform__process @@ -42,7 +42,7 @@ Workflow Platform Management :responsible: rl__technical_lead :approved_by: rl__process_community :supported_by: rl__safety_manager, rl__security_manager, rl__quality_manager - :input: wp__platform_mgmt, wp__project_mgt, wp__document_mgt_plan + :input: wp__platform_mgmt, wp__project_mgt, wp__document_mgt_plan, wp__config_mgt_plan :output: wp__issue_track_system :contains: gd_temp__platform__mgmt_plan, gd_guidl__platform__mgmt_plan, gd_guidl__documentation, gd_chklst__documentation__review :has: doc_concept__platform__process, doc_getstrt__platform__process diff --git a/process/process_areas/release_management/guidance/release_guideline.rst b/process/process_areas/release_management/guidance/release_guideline.rst index 47b8514c8f..10bb9bf9e8 100644 --- a/process/process_areas/release_management/guidance/release_guideline.rst +++ b/process/process_areas/release_management/guidance/release_guideline.rst @@ -46,6 +46,7 @@ Software Module Release * Update the version number according to the versioning policy of your module (defined in release management part of the :need:`gd_temp__platform__mgmt_plan`). * Prepare release notes documenting the changes, improvements, and bug fixes. + * Check if all planned configuration items are in correct state (i.e. work products are valid, external libraries/tools are used in the correct released version). * Ensure the module's safety package is available and complete. * Tag the release in the GitHub repository. @@ -81,6 +82,7 @@ Platform Release * Check if modules are released. * Update the platform version number according to the versioning policy (defined in release management part of the :need:`gd_temp__platform__mgmt_plan`). * Prepare platform release notes summarizing the updates from all integrated software modules. + * Check if all planned configuration items are in correct state (i.e. work products are valid, external libraries/tools are used in the correct released version). * Ensure the relevant safety packages are available and complete. * Tag the platform release in the GitHub repository.