From 2bd7adefeeb973c1dced4f427d4da20944f65ce1 Mon Sep 17 00:00:00 2001 From: "jhr2hi@bosch.com" Date: Wed, 3 Jun 2026 10:56:40 +0200 Subject: [PATCH] update docu for single feature repo structure --- index.rst | 187 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 135 insertions(+), 52 deletions(-) diff --git a/index.rst b/index.rst index 6cfdd3f..3314a42 100644 --- a/index.rst +++ b/index.rst @@ -35,58 +35,141 @@ Module Layout The module template includes the following top-level structure: -.. code-block:: text - - / # Root folder of the module, subfolder only if more than one module exists in the repository - ├── .github/ - │ └── workflows/ # CI/CD pipelines - ├── docs/ # Global documentation of the module - │ ├── features/ # Feature documentation and architecture - │ │ └── / # Feature folder parts for each feature which should be in module documentation - │ │ ├── architecture/ # Feature architecture [wp__feature_arch] and of architecture review [wp__sw_arch_verification] - │ │ ├── safety_analysis/ # Feature safety analysis artifacts ([wp__feature_fmea], [wp__feature_dfa], [wp__requirements_feat_aou]) - │ │ ├── safety_planning/ # Feature safety planning artifacts - │ │ ├── security_analysis/ # Feature security analysis artifacts [wp__feature_security_analysis] - │ │ └── security_planning/ # Feature security planning artifacts - │ ├── manuals/ # Module manual, integration manual, table of assumptions of use, - │ │ # safety manual [wp__module_safety_manual], - │ │ # needs table of [wp__requirements_feat_aou] - │ │ # security manual [wp__module_security_manual] - │ ├── release/ # Module release note [wp__module_sw_release_note] - │ ├── safety_mgt/ # Module safety plan [wp__module_safety_plan], - │ │ # module safety package [wp__module_safety_package], - │ │ # formal document and safety analysis reviews [wp__fdr_reports] - │ ├── security_mgt/ # Module security plan [wp__module_security_plan], - │ │ # module security package [wp__module_security_package], - │ │ # formal document reviews [wp__fdr_reports_security], - │ │ # module SW bill of material [wp__sw_module_sbom] - │ └── verification_report/ # Module verification report, - │ # module verifications [wp__verification_module_ver_report], - ├── examples/ # Usage examples for the module / features - ├── score/ # Components of the module - │ ├── tests/ # Module-level tests (e.g., feature integration tests, system tests) [wp__verification_comp_int_test] - │ └── / # Component folder for each component of the module - │ ├── docs/ # Documentation of the component - │ │ ├── architecture/ # Component architecture [wp__component_arch] - │ │ │ # (only if lower level components exist) - | | | # architecture review [wp__sw_arch_verification], - │ │ ├── detailed_design/ # Detailed design [wp__sw_implementation] - │ │ │ # code inspection [wp__sw_implementation_inspection] - │ │ ├── requirements/ # Component requirements [wp__requirements_comp],[wp__requirements_inspect] - │ │ ├── safety_analysis/ # Safety analysis [wp__sw_component_fmea], [wp__sw_component_dfa], [wp__requirements_comp_aou] - | | | # Component classification [wp__sw_component_class] for pre-existing software - │ │ │ # (only if component architecture exists) - │ │ ├── security_analysis/ # Security analysis [wp__sw_component_security_analysis] - │ │ │ # (only if component architecture exists) - │ │ └── manuals/ # User documentation (of a single component, e.g., user manual of a library component, optional) - │ └── src/ # Source files, include files, unit tests [wp__verification_sw_unit_test], - │ ├── / # Lower level component (follows structure) - │ └── tests/ # Component-level tests (e.g., unit tests) [wp__verification_sw_unit_test] - ├── MODULE.bazel # Bazel module definition - ├── BUILD # Root build rules - ├── project_config.bzl # Project metadata used by Bazel macros - └── README.md # Entry point of the repository - +.. parsed-literal:: + + / -> Folder containing all artifacts corresponding to one module. + │ As folder optional if the repository only contains a single module. + ├── docs/ -> Documentation of the module + │ ├── features/ -> All features of the module. + │ │ └── / -> Features including sub-folders and feature/component (change) request + │ │ │ [:need:`wp__feat_request`], [:need:`wp__cmpt_request`] + │ │ ├── architecture/ -> Feature architecture + │ │ │ [:need:`wp__feature_arch`], [:need:`wp__sw_arch_verification`] + │ │ ├── safety_analysis/ -> Safety analysis on feature level + │ │ │ [:need:`wp__feature_fmea`], [:need:`wp__feature_dfa`] + │ │ ├── safety_planning/ -> Feature specific safety workproducts planning + │ │ │ [:need:`wp__platform_safety_plan`] + │ │ ├── security_analysis/ -> Security analysis on feature level + │ │ │ [:need:`wp__feature_security_analysis`] + │ │ └── security_planning/ -> Feature specific security workproducts planning + │ │ [:need:`wp__platform_security_plan`] + │ ├── manuals/ -> Module manual, e.g. integration manual, assumptions of use, + │ │ safety manual [:need:`wp__requirements_comp_aou`], + │ │ [:need:`wp__requirements_feat_aou`], + │ │ [:need:`wp__module_safety_manual`], + │ │ security_manual [:need:`wp__module_security_manual`]. + │ ├── release/ -> Module release note [:need:`wp__module_sw_release_note`], + │ │ module release plan [:need:`wp__module_sw_release_plan`], + │ ├── safety_mgt/ -> Module safety plan [:need:`wp__module_safety_plan`], + │ │ module safety package [:need:`wp__module_safety_package`], + │ │ formal documents reviews [:need:`wp__fdr_reports`], + │ │ safety analysis formal reviews [:need:`wp__fdr_reports`], + │ │ safety tailoring [:need:`wp__safety_tailoring`] + │ │ safety component classification [:need:`wp__sw_component_class`] + │ ├── security_mgt/ -> Module security plan [:need:`wp__module_security_plan`], + │ │ module security package [:need:`wp__module_security_package`], + │ │ formal documents reviews [:need:`wp__fdr_reports_security`], + │ │ module SW bill of material [:need:`wp__sw_module_sbom`] + │ └── verification_report/ -> Module verification report + │ module verifications [:need:`wp__verification_module_ver_report`], + └── score/ -> Folder containing all artifacts corresponding to the components of the module. + ├── / -> Components of the module. + │ │ Folder containing all artifacts corresponding to one component. + │ ├── docs/ -> Documentation of the component + │ │ ├── architecture/ -> Component architecture (only if lower level components exist) + │ │ │ [:need:`wp__component_arch`]. + │ │ ├── detailed_design/ -> Detailed Design [:need:`wp__sw_implementation`] and + │ │ │ Detail design + code inspection [:need:`wp__sw_implementation_inspection`], + │ │ ├── manuals/ -> User documentation of a single component + │ │ │ (e.g., user manual of a library, optional) + │ │ ├── requirements/ -> Component requirements [:need:`wp__requirements_comp`], + │ │ │ requirements inspection [:need:`wp__requirements_inspect`] + │ │ ├── safety_analysis/ -> Safety analysis on component level (only if component architecture exists) + │ │ │ [:need:`wp__sw_component_fmea`], [:need:`wp__sw_component_dfa`] + │ │ └── security_analysis/ -> Security analysis on component level (only if component architecture exists) + │ └── src/ -> Source files of the component consisting of + │ │ Include and source Files [:need:`wp__sw_implementation`] + │ │ Test doubles + │ │ Unit tests [:need:`wp__verification_sw_unit_test`] + │ ├── / -> lower level component following folder structure + │ └── tests/ -> Component-level tests (e.g., unit tests) + │ [:need:`wp__verification_sw_unit_test`] + └── tests/ -> Module-level tests (e.g., feature integration tests, system tests) + [:need:`wp__verification_comp_int_test`] + Feature Integration tests [:need:`wp__verification_feat_int_test`] + +.. note:: + + The feature-specific subfolder under ``docs/features//`` is only necessary + if more than one feature is implemented in the module. + +Module Folder Structure (Single-Feature Variant) +------------------------------------------------ + +The following variant keeps the same structure but removes the additional +feature-name nesting under ``docs/features/``. In this case, the ``features/`` +subfolder is optional and omitted. This variant is intended for modules that only implement a single feature, to avoid unnecessary nesting. +For identification of the single feature, the repository name or module name should be replicate the feature name. + +.. parsed-literal:: + + / -> Folder containing all artifacts corresponding to one module. + │ As folder optional if the repository only contains a single module. + ├── docs/ -> Documentation of the module + │ ├── architecture/ -> Feature architecture + │ │ [:need:`wp__feature_arch`], [:need:`wp__sw_arch_verification`] + │ ├── safety_analysis/ -> Safety analysis on feature level + │ │ [:need:`wp__feature_fmea`], [:need:`wp__feature_dfa`] + │ ├── safety_planning/ -> Feature specific safety workproducts planning + │ │ [:need:`wp__platform_safety_plan`] + │ ├── security_analysis/ -> Security analysis on feature level + │ │ [:need:`wp__feature_security_analysis`] + │ ├── security_planning/ -> Feature specific security workproducts planning + │ │ [:need:`wp__platform_security_plan`] + │ ├── manuals/ -> Module manual, e.g. integration manual, assumptions of use, + │ │ safety manual [:need:`wp__requirements_comp_aou`], + │ │ [:need:`wp__requirements_feat_aou`], + │ │ [:need:`wp__module_safety_manual`], + │ │ security_manual [:need:`wp__module_security_manual`]. + │ ├── release/ -> Module release note [:need:`wp__module_sw_release_note`], + │ │ module release plan [:need:`wp__module_sw_release_plan`], + │ ├── safety_mgt/ -> Module safety plan [:need:`wp__module_safety_plan`], + │ │ module safety package [:need:`wp__module_safety_package`], + │ │ formal documents reviews [:need:`wp__fdr_reports`], + │ │ safety analysis formal reviews [:need:`wp__fdr_reports`], + │ │ safety tailoring [:need:`wp__safety_tailoring`] + │ │ safety component classification [:need:`wp__sw_component_class`] + │ ├── security_mgt/ -> Module security plan [:need:`wp__module_security_plan`], + │ │ module security package [:need:`wp__module_security_package`], + │ │ formal documents reviews [:need:`wp__fdr_reports_security`], + │ │ module SW bill of material [:need:`wp__sw_module_sbom`] + │ └── verification_report/ -> Module verification report + │ module verifications [:need:`wp__verification_module_ver_report`], + └── score/ -> Folder containing all artifacts corresponding to the components of the module. + ├── / -> Components of the module. + │ │ Folder containing all artifacts corresponding to one component. + │ ├── docs/ -> Documentation of the component + │ │ ├── architecture/ -> Component architecture (only if lower level components exist) + │ │ │ [:need:`wp__component_arch`]. + │ │ ├── detailed_design/ -> Detailed Design [:need:`wp__sw_implementation`] and + │ │ │ Detail design + code inspection [:need:`wp__sw_implementation_inspection`], + │ │ ├── manuals/ -> User documentation of a single component + │ │ │ (e.g., user manual of a library, optional) + │ │ ├── requirements/ -> Component requirements [:need:`wp__requirements_comp`], + │ │ │ requirements inspection [:need:`wp__requirements_inspect`] + │ │ ├── safety_analysis/ -> Safety analysis on component level (only if component architecture exists) + │ │ │ [:need:`wp__sw_component_fmea`], [:need:`wp__sw_component_dfa`] + │ │ └── security_analysis/ -> Security analysis on component level (only if component architecture exists) + │ └── src/ -> Source files of the component consisting of + │ │ Include and source Files [:need:`wp__sw_implementation`] + │ │ Test doubles + │ │ Unit tests [:need:`wp__verification_sw_unit_test`] + │ ├── / -> lower level component following folder structure + │ └── tests/ -> Component-level tests (e.g., unit tests) + │ [:need:`wp__verification_sw_unit_test`] + └── tests/ -> Module-level tests (e.g., feature integration tests, system tests) + [:need:`wp__verification_comp_int_test`] + Feature Integration tests [:need:`wp__verification_feat_int_test`] Module / Feature Documentation ------------------------------