From 3e7f77008753f0b36a4bf9d0a7fd44ad2dca578e Mon Sep 17 00:00:00 2001 From: aschemmel-git Date: Thu, 7 May 2026 15:59:39 +0200 Subject: [PATCH] Inspection Component Req KVS --- .../requirements/chklst_req_inspection.rst | 115 +++++++++--------- docs/persistency/kvs/requirements/index.rst | 76 ++++++------ 2 files changed, 98 insertions(+), 93 deletions(-) diff --git a/docs/persistency/kvs/requirements/chklst_req_inspection.rst b/docs/persistency/kvs/requirements/chklst_req_inspection.rst index 8476439b..563728e5 100644 --- a/docs/persistency/kvs/requirements/chklst_req_inspection.rst +++ b/docs/persistency/kvs/requirements/chklst_req_inspection.rst @@ -15,11 +15,10 @@ .. document:: Persistency Requirements Inspection Checklist :id: doc__persistency_req_inspection_v2 - :status: draft + :status: valid :safety: ASIL_B :security: YES :realizes: wp__requirements_inspect - :tags: template Requirement Inspection Checklist ================================ @@ -34,9 +33,9 @@ Conduct As described in the concept :need:`doc_concept__wp_inspections` the following "inspection roles" are expected to be filled: -- content responsible (author): -- reviewer: -- moderator: +- content responsible (author): ``_ +- reviewer: ``_, ``_ +- moderator: ``_ - test expert: Checklist @@ -59,123 +58,125 @@ See also :need:`doc_concept__wp_inspections` for further information about revie * - REQ_01_01 - Is the requirement formulation template used? - see :need:`gd_temp__req_formulation`, this includes the use of "shall". - - - - + - YES + - All reqs use the generic term "The component shall ..." - * - REQ_02_01 - Is the requirement description *comprehensible* ? - If you think the requirement is hard to understand, comment here. - - - - - - + - NO + - - Several requirements use the term "snapshot" which is not explained. + - Unclear why all the requirements are using the post fix "_v2" + - In :need:`comp_req__persistency__default_value_types_v2` it is unclear what is the meaning of "only permitted" + - In :need:`comp_req__persistency__pers_data_schema_v2` it is not clear what downgrade means (it is also not required from the feature req). And it seems that really the application/user is responsible for thee versioning? + - In :need:`comp_req__persistency__field_mode_v2` - access to what? + - issue link TBD * - REQ_02_02 - Is the requirement description *unambiguous* ? - Especially search for "weak words" like "about", "etc.", "relevant" and others (see the internet documentation on this). This check shall be supported by tooling. - - - - - - + - NO + - :need:`comp_req__persistency__field_mode_v2` uses hard to verify term "as much as possible" + - issue link TBD * - REQ_02_03 - Is the requirement description *atomic* ? - A good way to think about this is to consider if the requirement may be tested by one (positive) test case or needs more of these. The requirement formulation template should also avoid being non-atomic already. Note that there are cases where also non-atomic requirements are the better ones, for example if those are better understandable. - - - - + - YES + - Several requirements use two "shall" which may indicate non atomic content, but the activities described like this are closely related so it is ok. - * - REQ_02_04 - Is the requirement description *feasible* ? - If at the time of the inspection the requirement has already some implementation, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_impl` shows this. In case the requirement has no implementation at the time of inspection (i.e. not implemented at least as "proof-of-concept"), a development expert should be invited to the Pull-Request review to explicitly check this item. - - - - + - YES + - Requirements are implemented already. - * - REQ_02_05 - Is the requirement description *independent from implementation* ? - This checkpoint should improve requirements definition in the sense that the "what" is described and not the "how" - the latter should be described in architecture/design derived from the requirement. But there can also be a good reason for this, for example we would require using a file format like JSON and even specify the formatting standard already on stakeholder requirement level because we want to be compatible. A finding in this checkpoint does not mean there is a safety problem in the requirement. - - - - + - YES + - The level of the requirements is component level, so some implementation detail is to be expected, but it seems not too detailed. - * - REQ_03_01 - Is the *linkage to the parent requirement* correct? - Linkage to correct levels and ASIL attributes is checked automatically, but it needs checking if the child requirement implements (at least) a part of the parent requirement. - - - - - - + - NO + - - :need:`comp_req__persistency__default_value_query_v2` does not implement a part of its linked :need:`feat_req__persistency__default_value_file` + - :need:`comp_req__persistency__default_value_cfg_v2` does not implement a part of its linked :need:`feat_req__persistency__reset_to_default` and :need:`feat_req__persistency__default_value_get` + - :need:`comp_req__persistency__default_val_chksum_v2` should only link to :need:`feat_req__persistency__default_value_file` + - stopped the inspection at this point - too many findings. Request rework of complete requirement set. + - issue link TBD * - REQ_04_01 - Is the requirement *internally and externally consistent*? - Does the requirement contradict other requirements within the same or higher levels? One may restrict the search to the feature for component requirements, for features to other features using same components. Is the description of the requirement consistent with all its attributes (if not already part of another check, e.g. does the title fit?). - - - - - - + - NO + - - Requirement :need:`comp_req__persistency__value_serialize_v2` speaks about serialization/deserialization of JSON, it is expected that this is a requirement for a "JSON" component and not for KVS + - All requirement IDs are using "persistency" as a component name, it should be "persistency_kvs" according to :need:`comp__persistency_kvs` + - issue link TBD * - REQ_05_01 - Do the software requirements consider *timing constraints*? - This checkpoint encourages to think about timing constraints even if those are not explicitly mentioned in the parent requirement. If the reviewer of a requirement already knows or suspects that the code execution will be consuming a lot of time, one should think of the expectation of a "user". - - - - + - YES + - Timing consideration is for example given in :need:`feat_req__persistency__async_api`. - * - REQ_06_01 - Does the requirement consider *external interfaces*? - The SW platform's external interfaces (to the user) are defined in the Feature Architecture, so the Feature and Component Requirements should determine the input data use and setting of output data for these interfaces. Are all output values defined? - - - - - - + - NO + - It is not completely defined how the operations in logic_arc_int__persistency__interface are used, for example "open" and "flush". + - issue link TBD * - REQ_07_01 - Is the *safety* attribute set correctly? - Derived requirements are checked automatically, see :need:`gd_req__req_linkage_safety`. But for the top level requirements (and also all AoU) this needs to be checked manually for correctness. - - - - + - YES + - automated check - * - REQ_07_02 - Is the attribute *security* set correctly? - For component requirements this checklist item is supported by automated check: "Every requirement which satisfies a feature requirement with security attribute set to YES inherits this". But the component requirements/architecture may additionally also be subject to a :need:`wp__sw_component_security_analysis`. - - - - + - YES + - automated check - * - REQ_08_01 - Is the requirement *verifiable*? - If at the time of the inspection already tests are created for the requirement, the answer is yes. This can be checked via traces, but also :need:`gd_req__req_attr_test_covered` shows this. In case the requirement is not sufficiently traced to test cases already, a test expert is invited to the inspection to give their opinion whether the requirement is formulated in a way that supports test development and the available test infrastructure is sufficient to perform the test. - - - - + - YES + - Reqs either already have a testlink or seem to easily testable. With the following exceptions (which need to be verified according to REQ_08_02): + + - :need:`comp_req__persistency__pers_data_version_v2` - absence of a feature cannot be tested + - :need:`comp_req__persistency__field_mode_v2` - as much as possible? + - :need:`comp_req__persistency__permission_control_v2` - non-implementation of a feature cannot be tested - * - REQ_08_02 - Is the requirement verifiable by design or code review in case it is not feasibly testable? - In very rare cases a requirement may not be verifiable by test cases, for example a specific non-functional requirement. In this case a requirement analysis verifies the requirement by design/code review. If such a requirement is in scope of this inspection, please check this here and link to the respective review record. A test expert is invited to the inspection to confirm their opinion that the requirement is not testable. - - - - - - + - NO + - Requirements mentioned in REQ_08_01 were not confirmed by design/code review to date. + - issue link TBD * - REQ_09_01 - Do the requirements that define a safety mechanism specify the error reaction leading to a safe state? - Alternatively to the safe state there could also be "repair" mechanisms. Also do not forget to consider REQ_05_01 for these. - - - - - - - - -.. attention:: - The above checklist entries must be filled according to your component requirements in scope. - -Note: If a Review ID is not applicable for your requirement, then state ""n/a" in status and comment accordingly in remarks. + - NO + - - :need:`comp_req__persistency__default_val_chksum_v2` - defines safety mechanism, no error reaction defined + - :need:`comp_req__persistency__pers_data_csum_v2` - defines part of safety mechanism, error reaction not needed + - :need:`comp_req__persistency__pers_data_csum_vrfy_v2` defines part of safety mechanism, no error reaction defined + - issue link TBD The following requirements in "valid" state and with "inspected" tag set are in the scope of this inspection: .. needtable:: - :filter: "component_name" in docname and "requirements" in docname and docname is not None and status == "valid" + :filter: docname is not None and "component_name" in docname and "requirements" in docname and status == "valid" :style: table :types: comp_req - :tags: component_name :columns: id;status;tags :colwidths: 25,25,25 :sort: title + And also the following AoUs in "valid" state and with "inspected" tag set (for these please answer the questions above as if the AoUs are requirements, except question REQ_03_01): .. needtable:: - :filter: "component_name" in docname and "requirements" in docname and docname is not None and status == "valid" + :filter: docname is not None and "component_name" in docname and "requirements" in docname and status == "valid" :style: table :types: aou_req - :tags: component_name :columns: id;status;tags :colwidths: 25,25,25 :sort: title - -.. attention:: - The above tables filtering must be updated according to your Component. - - - Modify ``component_name`` to be your Component Name in lower snake case diff --git a/docs/persistency/kvs/requirements/index.rst b/docs/persistency/kvs/requirements/index.rst index 465a1346..29f9a6e3 100644 --- a/docs/persistency/kvs/requirements/index.rst +++ b/docs/persistency/kvs/requirements/index.rst @@ -33,6 +33,7 @@ Component Requirements :satisfies: feat_req__persistency__support_datatype_keys :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall accept keys that consist solely of alphanumeric characters, underscores, or dashes. @@ -44,7 +45,8 @@ Component Requirements :satisfies: feat_req__persistency__support_datatype_keys :status: valid :belongs_to: comp__persistency_kvs - + :tags: inspected + The component shall encode each key as valid UTF-8. .. comp_req:: Key Uniqueness @@ -55,6 +57,7 @@ Component Requirements :satisfies: feat_req__persistency__support_datatype_keys :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall guarantee that each key is unique. @@ -66,6 +69,7 @@ Component Requirements :satisfies: feat_req__persistency__support_datatype_keys :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall limit the maximum length of a key to 32 bytes. @@ -77,7 +81,8 @@ Component Requirements :satisfies: feat_req__persistency__support_datatype_value :status: valid :belongs_to: comp__persistency_kvs - + :tags: inspected + The component shall accept only values of the following data types: Number, String, Null, Array[Value], or Dictionary{Key:Value}. @@ -89,6 +94,7 @@ Component Requirements :satisfies: feat_req__persistency__support_datatype_value :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall serialize and deserialize all values to and from JSON. @@ -100,6 +106,7 @@ Component Requirements :satisfies: feat_req__persistency__support_datatype_value :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall limit the maximum length of a value to 1024 bytes. @@ -111,6 +118,7 @@ Component Requirements :satisfies: feat_req__persistency__support_datatype_value,feat_req__persistency__default_values :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall support unset values and shall provide a default value when a value is unset. @@ -123,6 +131,7 @@ Component Requirements :satisfies: feat_req__persistency__support_datatype_value,feat_req__persistency__default_values :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall allow resetting a value to its default if a default is defined. @@ -135,6 +144,7 @@ Component Requirements :satisfies: feat_req__persistency__default_values,feat_req__persistency__default_value_get,feat_req__persistency__reset_to_default,feat_req__persistency__default_value_file :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall accept default values of only permitted value data types. @@ -147,6 +157,7 @@ Component Requirements :satisfies: feat_req__persistency__default_values,feat_req__persistency__default_value_get,feat_req__persistency__reset_to_default,feat_req__persistency__default_value_file :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall provide an API to retrieve default values. @@ -158,6 +169,7 @@ Component Requirements :satisfies: feat_req__persistency__default_values,feat_req__persistency__default_value_get,feat_req__persistency__reset_to_default,feat_req__persistency__default_value_file :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall allow configuration of default values in code or in a separate configuration file. @@ -170,6 +182,7 @@ Component Requirements :satisfies: feat_req__persistency__default_values,feat_req__persistency__default_value_get,feat_req__persistency__reset_to_default,feat_req__persistency__default_value_file :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall secure the configuration file for default values with an associated checksum file when default values are stored in a file. @@ -182,6 +195,7 @@ Component Requirements :satisfies: feat_req__persistency__cfg :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall allow configuration of KVS constraints at compile-time using source code constants or at runtime using a configuration file. @@ -194,6 +208,7 @@ Component Requirements :satisfies: feat_req__persistency__concurrency :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall implement thread-safe mechanisms to enable concurrent access to data without data races. @@ -206,6 +221,7 @@ Component Requirements :satisfies: feat_req__persistency__multiple_kvs :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall manage all runtime variables within an instance to enable creation and use of multiple KVS instances concurrently within a @@ -219,6 +235,7 @@ Component Requirements :satisfies: feat_req__persistency__integrity_check,feat_req__persistency__store_data :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall use the file API and the JSON data format to persist data. @@ -230,6 +247,7 @@ Component Requirements :satisfies: feat_req__persistency__integrity_check,feat_req__persistency__store_data :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall generate a checksum for each data file and shall store it alongside the data. @@ -242,6 +260,7 @@ Component Requirements :satisfies: feat_req__persistency__integrity_check,feat_req__persistency__load_data :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall verify the checksum when loading data. @@ -253,6 +272,7 @@ Component Requirements :satisfies: feat_req__persistency__integrity_check,feat_req__persistency__store_data :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall use the file API to persist data. @@ -264,6 +284,7 @@ Component Requirements :satisfies: feat_req__persistency__integrity_check,feat_req__persistency__store_data :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall use the JSON data format to persist data. @@ -275,6 +296,7 @@ Component Requirements :satisfies: feat_req__persistency__versioning,feat_req__persistency__update_mechanism :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall not provide built-in versioning. @@ -286,6 +308,7 @@ Component Requirements :satisfies: feat_req__persistency__versioning,feat_req__persistency__update_mechanism :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall use a JSON file storage format that enables the application to implement versioning, including upgrade and downgrade paths, @@ -299,6 +322,7 @@ Component Requirements :satisfies: feat_req__persistency__snapshot_create :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall create a snapshot each time data is stored. @@ -310,6 +334,7 @@ Component Requirements :satisfies: feat_req__persistency__cfg :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall maintain a configurable maximum number of snapshots. @@ -321,6 +346,7 @@ Component Requirements :satisfies: feat_req__persistency__snapshot_create :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall assign the ID 1 to the newest snapshot and shall increment the IDs of older snapshots accordingly. @@ -332,6 +358,7 @@ Component Requirements :satisfies: feat_req__persistency__snapshot_remove, feat_req__persistency__snapshot_restore :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall rotate and delete the oldest snapshot when the maximum number is reached. @@ -343,6 +370,7 @@ Component Requirements :satisfies: feat_req__persistency__snapshot_restore :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall allow restoration of a snapshot by its ID. @@ -354,6 +382,7 @@ Component Requirements :satisfies: feat_req__persistency__snapshot_remove :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall allow deletion of individual snapshots. @@ -365,6 +394,7 @@ Component Requirements :satisfies: feat_req__persistency__dev_mode :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall provide an engineering mode that can be enabled during build time to display debugging and internal information. @@ -377,6 +407,7 @@ Component Requirements :satisfies: feat_req__persistency__prod_mode :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall provide a field mode that can be enabled during build time to restrict access as much as possible. @@ -389,6 +420,7 @@ Component Requirements :satisfies: feat_req__persistency__async_api :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall provide an asynchronous API in addition to the standard API. @@ -400,6 +432,7 @@ Component Requirements :satisfies: feat_req__persistency__access_control :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall rely on the underlying filesystem for access and permission management and shall not implement its own access or permission @@ -413,6 +446,7 @@ Component Requirements :satisfies: feat_req__persistency__access_control :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall report any access or permission errors encountered at the filesystem level to the application. @@ -425,6 +459,7 @@ Component Requirements :satisfies: feat_req__persistency__async_api, feat_req__persistency__async_completion :status: valid :belongs_to: comp__persistency_kvs + :tags: inspected The component shall provide an API for registering callbacks that are triggered by data change events. @@ -432,44 +467,13 @@ Component Requirements Assumption of Use Requirements ------------------------------ -.. code-block:: rst - - .. aou_req:: Next Title - :id: aou_req__component_name__next_title - :reqtype: Process - :security: YES - :safety: ASIL_B - :status: invalid - - The Component User shall do xyz to use the component safely/securely +none Environmental Requirements -------------------------- -.. code-block:: rst - - .. aou_req:: Another Title - :id: aou_req__component_name__another_title - :reqtype: Process - :security: YES - :safety: ASIL_B - :status: invalid - :tags: environment - - The Component shall only be used in a xyz environment to ensure its proper functioning. - -Hints ------ - -.. attention:: - The above directives must be updated according to your feature requirements. - - - Replace the example content by the real content for your first requirement (according to :need:`gd_guidl__req_engineering`) - - Set ``safety`` and ``security`` to the right value (ASIL B/QM; YES/NO) - - Set ``reqtype`` with a link to the right value () - - Add other needed requirements for your feature - - Set ``status`` to ``valid`` and start the review/merge process +none -.. needextend:: docname is not None and "persistency/kvs/docs/requirements" in docname +.. needextend:: docname is not None and "persistency/kvs/requirements" in docname :+tags: kvs