Skip to content

Commit 948311d

Browse files
RolandJentschETASRolandJentschETAS
authored
update docu for single feature repo structure (#83)
Signed-off-by: RolandJentschETAS <135332348+RolandJentschETAS@users.noreply.github.com>
1 parent fbc128d commit 948311d

1 file changed

Lines changed: 63 additions & 1 deletion

File tree

‎index.rst‎

Lines changed: 63 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ Module Layout
3535

3636
The module template includes the following top-level structure:
3737

38-
.. code-block:: text
38+
.. parsed-literal::
3939
4040
<module_name>/ # Root folder of the module, subfolder only if more than one module exists in the repository
4141
├── .github/
@@ -87,6 +87,68 @@ The module template includes the following top-level structure:
8787
├── project_config.bzl # Project metadata used by Bazel macros
8888
└── README.md # Entry point of the repository
8989
90+
.. note::
91+
92+
The feature-specific subfolder under ``docs/features/<feature_name>/`` is only necessary
93+
if more than one feature is implemented in the module.
94+
95+
Module Folder Structure (Single-Feature Variant)
96+
------------------------------------------------
97+
98+
The following variant keeps the same structure but removes the additional
99+
feature-name nesting under ``docs/features/``. In this case, the ``features/``
100+
subfolder is optional and omitted. This variant is intended for modules that only implement a single feature, to avoid unnecessary nesting.
101+
For identification of the single feature, the repository name or module name should be replicate the feature name.
102+
103+
.. parsed-literal::
104+
105+
<module_name>/ # Root folder of the module, subfolder only if more than one module exists in the repository
106+
├── .github/
107+
│ └── workflows/ # CI/CD pipelines
108+
├── docs/ # Global documentation of the module and the single feature
109+
│ ├── architecture/ # Feature architecture [wp__feature_arch] and of architecture review [wp__sw_arch_verification]
110+
│ ├── safety_analysis/ # Feature safety analysis artifacts ([wp__feature_fmea], [wp__feature_dfa], [wp__requirements_feat_aou])
111+
│ ├── safety_planning/ # Feature safety planning artifacts
112+
│ ├── security_analysis/ # Feature security analysis artifacts [wp__feature_security_analysis]
113+
│ ├── security_planning/ # Feature security planning artifacts
114+
│ ├── manuals/ # Module manual, integration manual, table of assumptions of use,
115+
│ │ # safety manual [wp__module_safety_manual],
116+
│ │ # needs table of [wp__requirements_feat_aou]
117+
│ │ # security manual [wp__module_security_manual]
118+
│ ├── release/ # Module release note [wp__module_sw_release_note]
119+
│ ├── safety_mgt/ # Module safety plan [wp__module_safety_plan],
120+
│ │ # module safety package [wp__module_safety_package],
121+
│ │ # formal document and safety analysis reviews [wp__fdr_reports]
122+
│ ├── security_mgt/ # Module security plan [wp__module_security_plan],
123+
│ │ # module security package [wp__module_security_package],
124+
│ │ # formal document reviews [wp__fdr_reports_security],
125+
│ │ # module SW bill of material [wp__sw_module_sbom]
126+
│ └── verification_report/ # Module verification report,
127+
│ # module verifications [wp__verification_module_ver_report],
128+
├── examples/ # Usage examples for the module / features
129+
├── score/ # Components of the module
130+
│ ├── tests/ # Module-level tests (e.g., feature integration tests, system tests) [wp__verification_feat_int_test]
131+
│ └── <component_name>/ # Component folder for each component of the module
132+
│ ├── docs/ # Documentation of the component
133+
│ │ ├── architecture/ # Component architecture [wp__component_arch]
134+
│ │ │ # (only if lower level components exist)
135+
| | | # architecture review [wp__sw_arch_verification],
136+
│ │ ├── detailed_design/ # Detailed design [wp__sw_implementation]
137+
│ │ │ # code inspection [wp__sw_implementation_inspection]
138+
│ │ ├── requirements/ # Component requirements [wp__requirements_comp],[wp__requirements_inspect]
139+
│ │ ├── safety_analysis/ # Safety analysis [wp__sw_component_fmea], [wp__sw_component_dfa], [wp__requirements_comp_aou]
140+
| | | # Component classification [wp__sw_component_class] for pre-existing software
141+
│ │ │ # (only if component architecture exists)
142+
│ │ ├── security_analysis/ # Security analysis [wp__sw_component_security_analysis]
143+
│ │ │ # (only if component architecture exists)
144+
│ │ └── manuals/ # User documentation (of a single component, e.g., user manual of a library component, optional)
145+
│ ├── src/ # Source files, include files, unit tests [wp__verification_sw_unit_test],
146+
│ │ └── <lower_level_comp>/ # Lower level component (follows <component_name> structure)
147+
│ └── tests/ # Component-level tests (e.g., integration or complex unit tests) [wp__verification_comp_int_test]
148+
├── MODULE.bazel # Bazel module definition
149+
├── BUILD # Root build rules
150+
├── project_config.bzl # Project metadata used by Bazel macros
151+
└── README.md # Entry point of the repository
90152
91153
Module / Feature Documentation
92154
------------------------------

0 commit comments

Comments
 (0)