121 lines
3.9 KiB
ReStructuredText
121 lines
3.9 KiB
ReStructuredText
.. _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 <https://docs.zephyrproject.org/latest/safety/safety_overview.html#general-safety-scope>`_
|
|
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
|
|
<https://github.com/zephyrproject-rtos/reqmgmt>`__
|
|
|
|
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 <https://strictdoc.readthedocs.io/en/stable/>`_, 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 <https://alistairmavin.com/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.
|