doc: safety: Requirment repo and guidelines #71953

simhein · 2024-04-25T15:19:11Z

Add documentation to point to the requirements repository and give the contributors a guideline how to add requirements to that repository.

nashif · 2024-04-30T12:17:43Z

doc/safety/safety_requirements.rst

+=========================================
+* System Requirements
+
+.. note::


why do you need the note here? drop it, should be just a normal paragraph

nashif · 2024-04-30T12:17:52Z

doc/safety/safety_requirements.rst

+
+* Software Requirements
+
+.. note::


Timotheous · 2024-05-07T16:12:21Z

doc/safety/safety_requirements.rst

+  System requirements describe the behaviour of the Zephyr RTOS (= the system here).
+  They describe the functionality of the Zephyr RTOS of a very high level point of view,
+  without going into details of the functionality itself.
+  The target of the system requirements is to get an overview of the included features of


Suggested change

The target of the system requirements is to get an overview of the included features of

The target of the system requirements is to get an overview of the currently implemented features of

doc/safety/safety_requirements.rst

Timotheous · 2024-05-07T16:40:08Z

doc/safety/safety_requirements.rst

+   `EARS
+   <https://alistairmavin.com/ears/>`__ Syntax for writing requirements.
+   But we also accept contributions in other formats as long as the characteristics
+   of a requirement from above are met.


Elevate note to a section:

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 accepted as long as the characteristics
of a requirement from above are met.

.. note::
If you want to contribute to the requirements effort but don't know how to write requirements
or if you are new to writing requirements, we recommend to look into the
EARS <https://alistairmavin.com/ears/>__ Syntax for writing requirements.
But we also accept contributions in other formats as long as the characteristics
of a requirement from above are met.

I could not figure out how to replace multiple lines.

I could not figure out how to replace multiple lines.

no problem I got your point here.

tobiaskaestner · 2024-05-14T13:35:52Z

doc/safety/safety_requirements.rst

+Guidelines
+**********
+Following are the guidelines for the requirements repository and what the safety committee
+expects when new requirements are added to the repository


suggestion: the word 'new' might be misleading as the previous paragraph made the explicit statement that no new requirements are to be created. I think "when requirements are added to the repository is" is sufficient

tobiaskaestner · 2024-05-14T13:36:35Z

doc/safety/safety_requirements.rst

+
+Scope
+=====
+The scope of the requirements are the **KERNEL** functionality.


polish: "are the KERNEL functionalities" or "is the KERNEL functionality

doc/safety/safety_requirements.rst

tobiaskaestner · 2024-05-14T13:44:56Z

doc/safety/safety_requirements.rst

+
+#. Don't add a requirement UID filed for new requirements
+#. After finishing work on the new Requirements execute strictDoc manage auto-uid
+#. Add linking of the requirements with the new distributed UIDs


issue: This step isn't clear to me. Where are links needed and what exactly do you mean with "new distributed UIDs?

I recall the discussion on how to manage UIDs and do not recall the details.
Is there a reference in the StrictDoc "Users Guide" covering this? I hope.
Is there a StrictDoc "Users Guide"?

issue: This step isn't clear to me. Where are links needed and what exactly do you mean with "new distributed UIDs?

with links the links between requirements are meant. Added the missing information.
I mean with new distributed UIDs the UIDs which are generated by the tool itself.

I recall the discussion on how to manage UIDs and do not recall the details. Is there a reference in the StrictDoc "Users Guide" covering this? I hope. Is there a StrictDoc "Users Guide"?

The discussion was on the mailing list, how to manage UIDs. This was actual my proposal how to handle UIDs there was no objections against it and no counter proposal. The proposal uses commands which are provided and handled by the stricDoc tool. The user guide can be found here: https://strictdoc.readthedocs.io/en/stable/strictdoc_01_user_guide.html

tobiaskaestner · 2024-05-14T13:47:30Z

doc/safety/safety_requirements.rst

+
+Requirement Types:
+==================
+* Functional


suggestion: Perhaps elaborate a bit on what makes requirements functional vs non-functional. I guess the main distinction is whether they can be verified by testing or not, see my comment above

doc/safety/safety_requirements.rst

tobiaskaestner · 2024-05-14T13:51:31Z

doc/safety/safety_requirements.rst

+Characteristics of a good requirement:
+======================================
+* Unambiguous
+* Testable (verifiable)


nitpick: Testable is one verification strategy but not all verification happens through testing. IMHO make this read Verifiable (testable) or even Verifiable (e.g. testable for functional requirements)

doc/safety/safety_requirements.rst

kartben · 2024-05-23T16:55:33Z

doc/safety/safety_requirements.rst

+
+Scope
+=====
+The scope of the requirements are the **KERNEL** functionalities.


Suggested change

The scope of the requirements are the **KERNEL** functionalities.

The scope of the requirements covers the KERNEL functionalities.

kartben · 2024-05-23T16:56:42Z

doc/safety/safety_requirements.rst

+The safety committee drive the effort to gather requirements to reflect the **actual** state of the
+implementation in requirements form, because of the route 3s approach of the projects safety
+effort. It is **NOT** the intention to create a new set of requirements to add them into the project
+to request new features.


Suggested change

The safety committee drive the effort to gather requirements to reflect the **actual** state of the

implementation in requirements form, because of the route 3s approach of the projects safety

effort. It is **NOT** the intention to create a new set of requirements to add them into the project

to request new features.

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.

kartben · 2024-05-23T16:57:17Z

doc/safety/safety_requirements.rst

+Following are the guidelines for the requirements repository and what the safety committee
+expects when requirements are added to the repository


Suggested change

Following are the guidelines for the requirements repository and what the safety committee

expects when requirements are added to the repository

Below are the guidelines for the requirements repository and the expectations of the safety

committee when adding requirements to the repository.

kartben · 2024-05-23T16:57:53Z

doc/safety/safety_requirements.rst

+
+Consistency
+===========
+Consistency across all requirements. The language and choice of words shall be consistent.


Suggested change

Consistency across all requirements. The language and choice of words shall be consistent.

Maintain consistency across all requirements. The language and choice of words shall be consistent.

kartben · 2024-05-23T16:58:56Z

doc/safety/safety_requirements.rst

+* System Requirements:
+
+  System requirements describe the behaviour of the Zephyr RTOS (= the system here).
+  They describe the functionality of the Zephyr RTOS of a very high level point of view,


Suggested change

They describe the functionality of the Zephyr RTOS of a very high level point of view,

They describe the functionality of the Zephyr RTOS from a high-level perspective,

kartben · 2024-05-23T17:10:05Z

doc/safety/safety_requirements.rst

+* System Requirements:
+


Suggested change

* System Requirements:

System Requirements

kartben · 2024-05-23T17:10:21Z

doc/safety/safety_requirements.rst

+* Software Requirements:
+


Suggested change

* Software Requirements:

Software Requirements

kartben · 2024-05-23T17:14:27Z

doc/safety/safety_requirements.rst

+For the requirements management the tool `strictDoc
+<https://strictdoc.readthedocs.io/en/stable/>`__
+is used, therefore the UID (Unique identifier) handling shall be handled by the tool and this can be achived by Following
+handling:


Suggested change

For the requirements management the tool `strictDoc

<https://strictdoc.readthedocs.io/en/stable/>`__

is used, therefore the UID (Unique identifier) handling shall be handled by the tool and this can be achived by Following

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:

Is it intended to add the ``` after steps? This change cause doc build errors.

Definitely not intended, sorry!

kartben · 2024-05-23T17:14:57Z

doc/safety/safety_requirements.rst

+is used, therefore the UID (Unique identifier) handling shall be handled by the tool and this can be achived by Following
+handling:
+
+#. Don't add a requirement UID filed for new requirements


Suggested change

#. Don't add a requirement UID filed for new requirements

#. Don't fill in the requirement UID when creating new requirements

In this case the complete filed don't need to be added for a requirement,

kartben · 2024-05-23T17:16:04Z

doc/safety/safety_requirements.rst

+* `EARS
+  <https://alistairmavin.com/ears/>`__ is a good reference.
+  Particularly if you are unfamiliar with requirements writing.
+* Other formats accepted as long as the characteristics


make these two bullet points sub-bullet points of "Use of a recognized..."

doc/safety/safety_requirements.rst

tobiaskaestner · 2024-05-24T08:00:05Z

doc/safety/safety_requirements.rst

+
+Introduction
+************
+The safety committee drive the effort to gather requirements to reflect the **actual** state of the


praise:

Suggested change

The safety committee drive the effort to gather requirements to reflect the **actual** state of the

The safety committee drives the effort to gather requirements to reflect the **actual** state of the

tobiaskaestner · 2024-05-24T08:01:37Z

doc/safety/safety_requirements.rst

+Introduction
+************
+The safety committee drive the effort to gather requirements to reflect the **actual** state of the
+implementation in requirements form, because of the route 3s approach of the projects safety


suggestion: route 3S is a 61508 specific term, perhaps worth adding a comment or reference to the glossary. I am pretty sure not everybody will immediately know what this means.

I will ad a linkt to : https://docs.zephyrproject.org/latest/safety/safety_overview.html#general-safety-scope where the route 3s is described.

simhein · 2024-06-03T14:21:07Z

@kartben can you take another look, all comments should have been addressed

kartben · 2024-06-10T09:10:48Z

pushed minor updates to fix formatting for definition list as I figured it would be quicker than another roundtrip of request for changes, Almost messed up your PR in the process though, sorry @simhein :)

LGTM, thanks!

Add documentation to point to the requirements repository and give the contributors a guideline how to add requirements to that repository. Signed-off-by: Simon Hein <Shein@baumer.com>

simhein · 2024-06-10T14:18:01Z

pushed minor updates to fix formatting for definition list as I figured it would be quicker than another roundtrip of request for changes, Almost messed up your PR in the process though, sorry @simhein :)

LGTM, thanks!

Thanks for taking a look again and saving the roundtrip 😄

simhein · 2024-06-10T21:38:24Z

@nashif and @tobiaskaestner can you have another look as well?

tobiaskaestner

LGTM, whatever isn't addressed in this PR we can follow up within subsequent PRs.

simhein force-pushed the doc_safety_req branch 2 times, most recently from c504c13 to 1140f41 Compare April 30, 2024 12:16

nashif reviewed Apr 30, 2024

View reviewed changes

doc/safety/safety_requirements.rst Outdated

* Software Requirements

.. note::

Copy link

Member

nashif Apr 30, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ditto

simhein reacted with thumbs up emoji

simhein force-pushed the doc_safety_req branch from 1140f41 to 74feaae Compare April 30, 2024 12:22

simhein force-pushed the doc_safety_req branch from 74feaae to 2acd0f6 Compare May 7, 2024 13:48

simhein marked this pull request as ready for review May 7, 2024 13:48

Timotheous suggested changes May 7, 2024

View reviewed changes

simhein force-pushed the doc_safety_req branch from 2acd0f6 to aaae401 Compare May 13, 2024 14:17

simhein linked an issue May 14, 2024 that may be closed by this pull request

Define how to add new Requierements zephyrproject-rtos/reqmgmt#13

Closed

5 tasks

simhein requested a review from a team May 14, 2024 11:43

simhein force-pushed the doc_safety_req branch from aaae401 to ce7d586 Compare May 14, 2024 12:02

tobiaskaestner reviewed May 14, 2024

View reviewed changes

simhein force-pushed the doc_safety_req branch from ce7d586 to 27f2c2c Compare May 21, 2024 12:02

simhein requested review from tobiaskaestner, Timotheous, nashif and a team and removed request for Timotheous May 21, 2024 12:02

simhein added area: Documentation Safety Tracked by the Safety WG labels May 22, 2024

kestewart mentioned this pull request May 23, 2024

RFC: Naming of the different Zephyr OS specification levels zephyrproject-rtos/reqmgmt#23

Closed

simhein assigned kartben May 23, 2024

simhein requested review from kartben and removed request for Timotheous May 23, 2024 15:47

kartben requested changes May 23, 2024

View reviewed changes

tobiaskaestner previously approved these changes May 24, 2024

View reviewed changes

simhein dismissed tobiaskaestner’s stale review via 30043ae May 24, 2024 11:42

simhein force-pushed the doc_safety_req branch from 27f2c2c to 30043ae Compare May 24, 2024 11:42

kartben force-pushed the doc_safety_req branch from e8bc0b9 to 7a33da5 Compare June 10, 2024 09:06

zephyrbot requested review from andyross, asbjornsabo, gmarull, hermabe, jhedberg, peter-mitsis, sjanc, Thalley and Vudentz June 10, 2024 09:07

kartben removed request for andyross, asbjornsabo, gmarull, hermabe, jhedberg, peter-mitsis, sjanc, Thalley and Vudentz June 10, 2024 09:07

kartben force-pushed the doc_safety_req branch from 7a33da5 to dc5a343 Compare June 10, 2024 09:09

doc: safety: Requirment repo and guidelines

643ce7d

Add documentation to point to the requirements repository and give the contributors a guideline how to add requirements to that repository. Signed-off-by: Simon Hein <Shein@baumer.com>

kartben force-pushed the doc_safety_req branch from dc5a343 to 643ce7d Compare June 10, 2024 09:11

kartben approved these changes Jun 10, 2024

View reviewed changes

tobiaskaestner approved these changes Jun 13, 2024

View reviewed changes

nashif approved these changes Jun 13, 2024

View reviewed changes

nashif merged commit 02577af into zephyrproject-rtos:main Jun 13, 2024
16 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: safety: Requirment repo and guidelines #71953

doc: safety: Requirment repo and guidelines #71953

simhein commented Apr 25, 2024

nashif Apr 30, 2024

nashif Apr 30, 2024

Timotheous May 7, 2024

Timotheous May 7, 2024

Timotheous May 7, 2024

simhein May 13, 2024

tobiaskaestner May 14, 2024

tobiaskaestner May 14, 2024

tobiaskaestner May 14, 2024

Timotheous May 14, 2024

simhein May 21, 2024

tobiaskaestner May 14, 2024

tobiaskaestner May 14, 2024

kartben May 23, 2024

kartben May 23, 2024

kartben May 23, 2024

kartben May 23, 2024

kartben May 23, 2024

kartben May 23, 2024

kartben May 23, 2024

kartben May 23, 2024 •

edited

Loading

simhein May 24, 2024

kartben May 24, 2024

kartben May 23, 2024

simhein May 24, 2024

kartben May 23, 2024

tobiaskaestner May 24, 2024

tobiaskaestner May 24, 2024

simhein May 24, 2024

simhein commented Jun 3, 2024

kartben commented Jun 10, 2024

simhein commented Jun 10, 2024

simhein commented Jun 10, 2024

tobiaskaestner left a comment

	The target of the system requirements is to get an overview of the included features of
	The target of the system requirements is to get an overview of the currently implemented features of

	The scope of the requirements are the KERNEL functionalities.
	The scope of the requirements covers the KERNEL functionalities.

		Following are the guidelines for the requirements repository and what the safety committee
		expects when requirements are added to the repository

	Consistency across all requirements. The language and choice of words shall be consistent.
	Maintain consistency across all requirements. The language and choice of words shall be consistent.

	They describe the functionality of the Zephyr RTOS of a very high level point of view,
	They describe the functionality of the Zephyr RTOS from a high-level perspective,

	#. Don't add a requirement UID filed for new requirements
	#. Don't fill in the requirement UID when creating new requirements

	The safety committee drive the effort to gather requirements to reflect the actual state of the
	The safety committee drives the effort to gather requirements to reflect the actual state of the

doc: safety: Requirment repo and guidelines #71953

doc: safety: Requirment repo and guidelines #71953

Conversation

simhein commented Apr 25, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Syntax

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kartben May 23, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

simhein commented Jun 3, 2024

kartben commented Jun 10, 2024

simhein commented Jun 10, 2024

simhein commented Jun 10, 2024

tobiaskaestner left a comment

Choose a reason for hiding this comment

kartben May 23, 2024 •

edited

Loading