1.. _safety_requirements:
2
3Safety Requirements
4###################
5
6Introduction
7************
8
9The safety committee leads the effort to gather requirements that reflect the **actual** state of
10the implementation, following the `route 3s <https://docs.zephyrproject.org/latest/safety/safety_overview.html#general-safety-scope>`_
11approach of the project's safety effort. The goal is **NOT** to create new requirements to request
12additional features for the project.
13
14The requirements are gathered in the separate repository:
15`Requirement repository
16<https://github.com/zephyrproject-rtos/reqmgmt>`__
17
18Guidelines
19**********
20
21Below are the guidelines for the requirements repository and the expectations of the safety
22committee when adding requirements to the repository.
23
24Scope
25=====
26
27The scope of the requirements covers the KERNEL functionalities.
28
29Consistency
30===========
31
32Maintain consistency across all requirements. The language and choice of words shall be consistent.
33(See: `Syntax`_)
34
35Levels of requirements in the repository
36========================================
37
38System Requirements
39  System requirements describe the behaviour of the Zephyr RTOS (= the system here).
40  They describe the functionality of the Zephyr RTOS from a very high-level perspective,
41  without going into details of the functionality itself.
42  The purpose of the system requirements is to get an overview of the currently implemented features
43  of the Zephyr RTOS.
44  In other words a person writing these requirements usually has some knowledge of the Zephyr RTOS
45  Project as the requirements are specific to an RTOS.
46
47Software Requirements
48  Software requirements refine the system-level requirements  at a more granular level so
49  that each requirement can be tested.
50  These requirements define the specific actions the feature shall be able to execute and the
51  behavior of the feature.
52
53Requirement UID (Unique identifier) Handling
54============================================
55
56The tool used to manage requirements, `strictDoc <https://strictdoc.readthedocs.io/en/stable/>`_, is
57responsible for handling the Unique Identifier (UID) associated with each requirement. To manage
58UIDs, follow these steps:
59
60#. Don't add a requirement UID and UID field for new requirements
61#. After completing work on the new requirements execute: ``strictDoc manage auto-uid .``
62#. Establish links between the requirements with the new attributed UIDs if needed
63
64After doing this, the requirements are ready and a pull request can be created.
65The CI in the PR will check if the requirements UIDs are valid or if there are duplicates in it.
66If there are duplicates in the PR, these need to be resolved by rebasing and re-executing
67the steps above.
68
69Requirement Types
70=================
71
72* Functional
73* Non-Functional
74
75Requirement title convention
76============================
77
78Use short and succinct requirement titles.
79
80Pull Request requirement repository
81===================================
82
83* Adhere to the :ref:`contribute_guidelines` of the Zephyr Project.
84
85  * As long as they are applicable to the requirements repository.
86
87* Avoid creating large commits that contain both trivial and non-trivial changes.
88
89* Avoid moving and changing requirements in the same commit.
90
91Characteristics of a good requirement
92=====================================
93
94* Unambiguous
95* Verifiable (e.g. testable for functional requirements)
96* Clear (concise, succinct, simple, precise)
97* Correct
98* Understandable
99* Feasible (realistic, possible)
100* Independent
101* Atomic
102* Necessary
103* Implementation-free (abstract)
104
105Characteristics of a set of requirements
106========================================
107
108* Complete
109* Consistent
110* Non redundant
111
112Syntax
113======
114
115* Use of a recognized Requirements Syntax is recommended.
116
117  * `EARS <https://alistairmavin.com/ears/>`_ is a good reference. Particularly if you are
118    unfamiliar with requirements writing.
119
120  * Other formats are accepted as long as the characteristics of a requirement from above are met.
121