Config Mgt Audit fixes - rework

Ref: Resolves #88

Author: aschemmel-tech

process/folder_templates/index.rst

@@ -12,6 +12,8 @@
    # SPDX-License-Identifier: Apache-2.0
    # *******************************************************************************
 
+.. _folder_templates:
+
 Folder Templates
 ################
 

process/process_areas/configuration_management/configuration_concept.rst

@@ -28,12 +28,15 @@ 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 work products do we have?
+#. Which configuration items do we have?
 #. What tooling do we need?
 
 Stakeholders
@@ -45,9 +48,6 @@ Stakeholders
 
 #. :need:`Contributor <rl__contributor>` and :need:`Committer <rl__committer>`
 
-   * wants know which configuration items version has to be used as input for his work
+   * 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
-
-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)

process/process_areas/configuration_management/configuration_getstrt.rst

@@ -19,11 +19,12 @@ Getting Started
    :id: doc_getstrt__configuration__process
    :status: valid
 
-In case you are appointed as a :need:`Technical Lead <rl__technical_lead>` by the :need:`rl__project_lead` in the S-CORE project:
+In case you are appointed as a :need:`Technical Lead <rl__technical_lead>` by the :need:`rl__project_lead` in the project:
 
-* On platform level, process community already provided a draft configuration management plan,
-  based on the template <link>, just set it to "valid"
+* 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.

process/process_areas/configuration_management/configuration_workflow.rst

@@ -19,6 +19,6 @@ 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 workproducts and their versions) defining a SW Release on platform or module level
+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`

process/process_areas/configuration_management/guidance/configuration_templates.rst

@@ -20,7 +20,7 @@ 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
+   :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
 +++++++
@@ -51,78 +51,75 @@ note: for definition of "configuration items" check :need:`doc_concept__configur
 Approach
 ++++++++
 
-.. gd_guidl:: Configuration Guideline
-   :id: gd_guidl__configuration
-   :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
-
-   The steps below describe how configuration identification, retrieval, modification, branches and baselines, backup and recovery are organized.
+The steps below describe how configuration identification, retrieval, modification, branches and baselines, backup and recovery are organized.
 
 Lifecycle
 ^^^^^^^^^
 
-The configuration management of the S-CORE project is in place during the complete development lifecycle as described in :ref:`general_concepts_lifecycle`.
+The configuration management of the <project name> 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 std_req__aspice_40__SUP-8-BP1 and std_req__aspice_40__SUP-8-BP2.
+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 "structured text" Id, this includes documents identified as such (see project documents list in <link to doc__documentation_mgt_plan>).
+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 <link to doc__documentation_mgt_plan>.
 Ids are checked for uniqueness, see :need:`gd_req__configuration_uid`.
-"Structured text" is also used to document the work products properties/attributes defined in the process area descriptions.
+"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 other artefacts these are either
+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 S-CORE CI - CI build configuration identifies those by their version.
+- (external) tools/binaries to be built in <project name> CI - CI build configuration identifies those by their version.
 
 
 Retrieval
 ^^^^^^^^^
 
 <Describe how work products and files can be retrieved from versioning tooling.>
 Their content is defined in the process/workproducts and process_area/<area_name>/workproducts files.
-To find the location of the work products, the project's folder structure definition <add link> can be used.
+To find the location of the work products, the folder structure definition :ref:`folder_templates` can be used.
 <Describe how certain versions (also the ones for a certain baseline) of the work products and the change history can be displayed by the version management tool.>
 
-For other artefacts: these are pulled into S-CORE integration repository by forking to be handled as above.
+For other artefacts: these are pulled into <project name> integration repository by forking to be handled as above.
 
 
 Control and Modification
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-This should cover std_req__aspice_40__SUP-8-BP3 and std_req__aspice_40__SUP-8-BP4
+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 <rl__contributor>`
 and shared for review and incorporation into a main branch, which are after their acceptance merged by the :need:`Committer <rl__committer>`
-(this should be supported by version management/review tooling).
+(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 <link doc__platform_change_management_plan>.
 
-For other artefacts modifications are controlled by the CI build files which are also under configuration control.
+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 std_req__aspice_40__SUP-8-BP5
+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 S-CORE project the following types of branches will be used:
+Branches are used as a means of parallel development. In the <project name> 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 "release-<MAJOR_version>.<MINOR_version>
+  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 S-CORE all configuration items are kept in the version management tool, this means that there only needs to be one baseline for these
+In <project name> 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).
 <Describe how baselines are created by using the version management tool.>
 See also <link to doc__platform_release_management_plan>.
@@ -134,15 +131,15 @@ can decide how to ensure this (e.g. by development in main and cherrypick to rel
 Backup and Recovery
 ^^^^^^^^^^^^^^^^^^^
 
-This should cover std_req__aspice_40__SUP-8-BP8.
+This should cover :need:`std_req__aspice_40__SUP-8-BP8`
 
 <Describe how backup and recovery are covered in the project.>
-For the long term storage, additional measures should be taken, see :need:`gd_req__workproducts_storage`
+For the long term storage, additional measures should be taken, see :need:`gd_req__config__workproducts_storage`
 
 Status and Reporting
 ^^^^^^^^^^^^^^^^^^^^
 
-This should cover std_req__aspice_40__SUP-8-BP6 and std_req__aspice_40__SUP-8-BP7.
+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.
@@ -155,10 +152,14 @@ 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 S-CORE project
-("structured text" identification of work products).
+standard versioning tooling of the Eclipse Foundation and of the <project name> project
+("Docs-as-Code" identification of work products).
 The respective tools used in the project are:
 
-* versioning: <tool name>
-* structured text: <tool name>
-* CI build: <tool name>
+* versioning tool: <tool name>
+* "Docs-as-Code" tool: <tool name>
+* CI build tool: <tool name>
+
+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.

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?

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`.
 

process/process_areas/release_management/guidance/release_guideline.rst

@@ -46,7 +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 documents and work products are in valid state.
+   * 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.
 
@@ -82,7 +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 documents and work products are in valid state.
+   * 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.