From f08e32baf4720a7544f326a01529ef9a14cc2b84 Mon Sep 17 00:00:00 2001 From: Simon Hein Date: Wed, 24 Apr 2024 15:50:23 +0200 Subject: [PATCH] doc: safety: Requirment repo and guidelines Add documentation to point to the requirements repository and give the contributors a guideline how to add requirements to that repository. (cherry picked from commit 02577afe3a9928c6de5d8f87d9453f2a42d1ee2a) Original-Signed-off-by: Simon Hein GitOrigin-RevId: 02577afe3a9928c6de5d8f87d9453f2a42d1ee2a Change-Id: Ica033f8b5cfca6ed60dfdc7980ca71ae2720a0a2 Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/third_party/zephyr/+/5629500 Reviewed-by: Jeremy Bettis Tested-by: Jeremy Bettis Commit-Queue: Jeremy Bettis Tested-by: ChromeOS Prod (Robot) --- doc/safety/index.rst | 1 + doc/safety/safety_overview.rst | 2 +- doc/safety/safety_requirements.rst | 120 +++++++++++++++++++++++++++++ 3 files changed, 122 insertions(+), 1 deletion(-) create mode 100644 doc/safety/safety_requirements.rst diff --git a/doc/safety/index.rst b/doc/safety/index.rst index 1eb55d12a32..734f9a19ac4 100644 --- a/doc/safety/index.rst +++ b/doc/safety/index.rst @@ -11,3 +11,4 @@ for ensuring safety is addressed within the Zephyr project. :glob: safety_overview.rst + safety_requirements.rst diff --git a/doc/safety/safety_overview.rst b/doc/safety/safety_overview.rst index 9a17434e6d0..39a9da169df 100644 --- a/doc/safety/safety_overview.rst +++ b/doc/safety/safety_overview.rst @@ -99,7 +99,7 @@ which need to be reached to achieve an auditable code base: 1. Basic software quality standards a. :ref:`coding_guidelines` (including: static code analysis, coding style, etc.) - b. Requirements and requirements tracing + b. :ref:`safety_requirements` and requirements tracing c. Test coverage 2. Software architecture design principles diff --git a/doc/safety/safety_requirements.rst b/doc/safety/safety_requirements.rst new file mode 100644 index 00000000000..097c9063b49 --- /dev/null +++ b/doc/safety/safety_requirements.rst @@ -0,0 +1,120 @@ +.. _safety_requirements: + +Safety Requirements +################### + +Introduction +************ + +The safety committee leads the effort to gather requirements that reflect the **actual** state of +the implementation, following the `route 3s `_ +approach of the project's safety effort. The goal is **NOT** to create new requirements to request +additional features for the project. + +The requirements are gathered in the separate repository: +`Requirement repository +`__ + +Guidelines +********** + +Below are the guidelines for the requirements repository and the expectations of the safety +committee when adding requirements to the repository. + +Scope +===== + +The scope of the requirements covers the KERNEL functionalities. + +Consistency +=========== + +Maintain consistency across all requirements. The language and choice of words shall be consistent. +(See: `Syntax`_) + +Levels of requirements in the repository +======================================== + +System Requirements + System requirements describe the behaviour of the Zephyr RTOS (= the system here). + They describe the functionality of the Zephyr RTOS from a very high-level perspective, + without going into details of the functionality itself. + The purpose of the system requirements is to get an overview of the currently implemented features + of the Zephyr RTOS. + In other words a person writing these requirements usually has some knowledge of the Zephyr RTOS + Project as the requirements are specific to an RTOS. + +Software Requirements + Software requirements refine the system-level requirements at a more granular level so + that each requirement can be tested. + These requirements define the specific actions the feature shall be able to execute and the + behavior of the feature. + +Requirement UID (Unique identifier) Handling +============================================ + +The tool used to manage requirements, `strictDoc `_, is +responsible for handling the Unique Identifier (UID) associated with each requirement. To manage +UIDs, follow these steps: + +#. Don't add a requirement UID and UID field for new requirements +#. After completing work on the new requirements execute: ``strictDoc manage auto-uid .`` +#. Establish links between the requirements with the new attributed UIDs if needed + +After doing this, the requirements are ready and a pull request can be created. +The CI in the PR will check if the requirements UIDs are valid or if there are duplicates in it. +If there are duplicates in the PR, these need to be resolved by rebasing and re-executing +the steps above. + +Requirement Types +================= + +* Functional +* Non-Functional + +Requirement title convention +============================ + +Use short and succinct requirement titles. + +Pull Request requirement repository +=================================== + +* Adhere to the :ref:`contribute_guidelines` of the Zephyr Project. + + * As long as they are applicable to the requirements repository. + +* Avoid creating large commits that contain both trivial and non-trivial changes. + +* Avoid moving and changing requirements in the same commit. + +Characteristics of a good requirement +===================================== + +* Unambiguous +* Verifiable (e.g. testable for functional requirements) +* Clear (concise, succinct, simple, precise) +* Correct +* Understandable +* Feasible (realistic, possible) +* Independent +* Atomic +* Necessary +* Implementation-free (abstract) + +Characteristics of a set of requirements +======================================== + +* Complete +* Consistent +* Non redundant + +Syntax +====== + +* Use of a recognized Requirements Syntax is recommended. + + * `EARS `_ is a good reference. Particularly if you are + unfamiliar with requirements writing. + + * Other formats are accepted as long as the characteristics of a requirement from above are met.