Stakeholder Needs extraction of User Stories

[gregshue]

Add User Needs sdoc directory to hold User Need items so they can be referred to from Requirement items rather than copied into the USER_STORY. This is necessary since one User Need may be referenced by multiple requirement items, and one requirement item may need to reference multiple User Needs that it helps fulfill.

[gregshue]

As a result of a private conversation with @stanislaw I will reduce the scope of this PR to focus on Zephyr RTOS User and generate a few more fundamental needs of this user. The goal is to get the (near empty) document files and initial structure into the repository.

[gregshue]

I noticed these needs do not depend on Zephyr, so I'd prefer to rename the fragment file zephyr_rtos_user.sdoc to be product_manufacturer.sdoc. We should expect a file chip_vendor.sdoc will come along at some point.

[romkell]

• I fully agree to move the user story (from agile approaches) out of the existing requirement to support multiple linkage (as I stated in the req focus group meeting the user story were added to make pre-existing requirements more understandable were we had trouble to do so)
• I do not see why to formalize more than what an agile approach does
• I do not see why to split into several stakeholder. A device manufacturer, a chip vendor and a student will have 90% the same expectations of what an RTOS shall do/provide for them. There are 10% where the student does not care, where to the device manufacturer it is essential. We will get massive overlap.
• The different stakeholder needs / requests are currently gathered in github issues / RFCs in some way.
• I do not see how the user needs / requirements currently help to get together a requirements base for the existing code base that serves any qualifications (safety, security etc.).
• I am also convinced that I do not require any stakeholder needs to get a qualification (as manufacturer I can define a product/system -with requirements - that I believe suites my stakeholders. I can develop it and certify it. Dependent on whether with my assumptions I hit the stakeholders needs, I have a certified product or a certified brick.
• If we open that door now with user needs / requirements and link it to the rest of the requirements base, we will have to manage and maintain it (also for any certification if we us it) and build a process around it. It needs to be up-to-date and consistent.
• I highly recommend to postpone to start with user needs / requirements and re-focus on creating a requirements base for the existing code base and the so far defined scope that we want to (safety) certify with the openness to be able to extend the requirements base.

[gregshue]

Interesting comments from @romkell and @simhein. I think I can fill in some of the gaps and identify some of the incorrect assumptions. Please consider the following:

@romkell wrote

I do not see why to formalize more than what an agile approach does

This is a wonderfully open and honest statement. Thank you! Many people confuse the Agile Manifesto statements with Scrum or XP. This approach is actually very consistent with the Agile Manifesto once you recognize the following:

1. Regulators have specified the definition of "working software" to include the development process and documentary evidence - and tracing out content to make sure the software does nothing beyond what is required at the system level;
2. Most customers will not be collaborating with the Zephyr Project. I am almost the only Product Manufacturer collaborating on Requirements.

One of the struggles with an approach like Scrum is that the requirements/features are not cross-linked and the process does not thoroughly examine the collection for gaps, additions, and conflicts. This has led to security holes and probably safety issues.

will have 90% ...

This is an assumption. Gathering (eliciting) user needs will show if that assumption is correct.

I do not see why to split into several stakeholder.

From SEVOCAB (drawn from international standards like IEEE, ISO, IEC, etc):

stakeholder. (1) individual or organization having a right, share, claim, or interest in a system or in its possession of characteristics that meet their needs and expectations (ISO/IEC/IEEE 12207:2017 Systems and software engineering--Software life cycle processes, 3.1.59) (ISO/IEC/IEEE 15288:2023 Systems and software engineering--System life cycle processes, 3.44) (ISO/IEC/IEEE 24748-1:2018 Systems and software engineering--Life cycle management--Part 1: Guidelines for life cycle management, 3.51); ...

Stakeholders also include The Linux Foundation, TUV, regulators, project members, project participants, non-participating software development efforts providing integrations downstream. These span a very broad range of needs. The collection will be too large to manage as a flat list, and requirements must trace back to User Needs.

From SWEBOK v4 (public review draft):

Formally, a software requirement has been defined as [28]: • a condition or capability needed by a user to solve a problem or achieve an objective; • a condition or capability that must be met or possessed by a system or system component to satisfy a contract, standard, specification or other formally imposed document; • a documented representation or capability as in (1) or (2) above.

[28] ]ISO/IEC/IEEE, “ISO/IEC/IEEE 24765:2017 Systems and Software Engineering — Vocabulary,” 2nd ed. 2017

Documents get imposed on a set of software ultimately to meet User Needs.

The different stakeholder needs / requests are currently gathered in github issues / RFCs in some way.

Agreed, which is problematic as pointed out above. That will not be sufficient to be certified as meeting the EU Cybersecurity Act or EU RED directive. I expect it will also not be sufficient to meet some safety regulations.

I do not see how the user needs / requirements currently help

The System Requirements (the scope of the problem that will be solved) must trace up to Stakeholder Requirements (imposed constraints) and Stakeholder Needs (the breadth of the problem space that exists). IEC 62508 is introduced directly or indirectly as a Stakeholder Requirement.

I am also convinced that I do not require any stakeholder needs to get a qualification

You may not. Please allow that others may. AFAICT, I do.

re-focus on creating a requirements base for the existing code base

We are actually headed to the same goal. You will see this when I fill in more content. Here is the approximate tracing following the Requirements Engineering process. Tools will help us identify where a requirement is not met and where unintended functionality gets introduced.:

1. Stakeholder (User) Need: As a Product Manufacturer I need an RTOS to support Counting Semaphores so that I can reuse my existing RTOS-based designs.
2. System Requirement: The Zephyr Project shall produce an RTOS that provides Counting Semaphores (with tracing back to Stakeholder Requirements and/or Needs).
3. System Architecture: The Zephyr Project has a codebase containing a safe and secure RTOS providing Counting Semaphores. ...
4. Kernel Requirement: The Zephyr Kernel shall expose an interface for build-time initialization of a Counting Semaphore that ... (with tracing back to System Requirements).
5. Kernel Architecture: The Zephyr Kernel has a macro for statically instantiating and initializing a Counting Semaphore with ...
6. Kernel Architecture: The Zephyr Kernel has a component Counting Semaphore to be implemented in file sem.c that is responsible for ...
7. Interface Specification (within zephyr/kernel.h, and traced to interface requirements) ...
8. Interface Implementation (within kernel/sem.c)
9. Verification (within tests/.../kernel/sem*/ with test cases traced to interface specification.
10. Kernel File:

postpone to start with user needs / requirements

with the openness to be able to extend the requirements base.

Postponing and blocking doesn't sound very open to extensions.

From @simhein

user needs are also not the goal

Agreed. They are a dependency.

safety committee is looking for and try to achieve in this repository

If the Safety Committee is trying to gather requirements independent of Security Committee needs then it isn't fulfilling the responsibilities it accepted on behalf of the whole Zephyr Project. The Zephyr Project needs one set of requirements that fulfills both needs.

The easiest and most transparent way to see how this all fits together is by showing this with a freely available standard referenced by regulations relevant to the Zephyr Project. One example of this is ETSI 303 645, referenced by the EU Cybersecurity Act (regulation). As long as the requirements base is open to accepting content related to ETSI 303 645 then we can publicly demonstrate the entire process and solution even without submitting for security compliance approval.

[gregshue]

@romkell @simhein How about I trim this down to just the structure then migrate the User Story content into the new structure?

[gregshue]

@simhein @romkell I have trimmed this PR down to the document skeletons and extracted the User Stories from the system_requirements. Please review again.

[gregshue]

Feedback from 2024 Apr 25 Req Focus Group: Reduce this to relocating the existing User Story statements in the unfragmented stakeholder_needs.sdoc, without any further organizing sections.