Skip to content

update docu for single feature repo structure #83

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
RolandJentschETAS wants to merge 1 commit into
base: main
Choose a base branch
from
Open

update docu for single feature repo structure #83

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
187 changes: 135 additions & 52 deletions index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,58 +35,141 @@ Module Layout

The module template includes the following top-level structure:

.. code-block:: text

<module_name>/ # 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_name>/ # 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_name>/ # 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_comp>/ # Lower level component (follows <component_name> 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::

<module_name>/ -> 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.
│ │ └── <feature_name>/ -> 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.
├── <component_name>/ -> 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_comp>/ -> lower level component following <component_name> 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/<feature_name>/`` 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::

<module_name>/ -> 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.
├── <component_name>/ -> 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_comp>/ -> lower level component following <component_name> 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
------------------------------
Expand Down
Loading