The WHAT-WHY-HOW-API proposal

[stanislaw]

No description provided.

[haxtibal]

of the function

This implies we're talking about LLRs. Can HLRs also be described by WHAT/WHY/HOW?

[gregshue]

@haxtibal What definitions are you using for LLRs and HLRs?

[haxtibal]

From ELISA side we currently have a proposal for LLRs. Thus my demo contains only LLRs like this, and also the examples included in this PR are all LLRs.

I just thought that eventually there my arise the wish for HLRs. Then this PR would not be generic enough.

[stanislaw]

@gregshue good question. HLRs are not defined formally in the Linux proposal (just shared a link with you via email). The LLRs are defined as follows:

The aerospace standard (DO-178C) requires LLRs for projects in the high criticality (SWL A-C) range and describes them as, “software requirements from which Source Code can be directly implemented without further information”.

I think the closest reference in that proposal, therefore, is how DO-178C sees it. I am asking ChatGPT and I think it is accurate enough:

HLRs (High-Level Requirements) are implementation-independent. They describe what the software must do from a functional perspective without specifying how it is done. HLRs focus on external behavior and interactions.

LLRs (Low-Level Requirements) are much more detailed and are intended to guide the actual implementation. They describe how the software fulfills the HLRs, including algorithms, internal logic, data structures, control flow, and detailed behavior. While LLRs avoid specifying exact code, they are sufficiently detailed that a developer can implement the software directly from them and verify that the implementation meets the HLRs.

[gregshue]

How do you think LLRs and HLRs map to SWEBoK definitions of Stakeholder Requirement vs System Requirement vs System Element Requirement? SWEBoK also assumes each System Element will either be directly implemented or be identified as a System for a recursive decomposition.

I think answering these will show that the template must support capturing HLRs too.

[haxtibal]

how this function satisfies its parent requirement(s) referenced with
SPDX-Req-Ref

Could we mark WHY optional in case Ref is present? The parent link is the more important one. Knowing the parent, it's often obvious how a child contributes to a parent so that one can spare the WHY and use time for more critical things.

[stanislaw]

I am (slightly) against marking it as optional because, in the end, a developer will see a Ref hash pointing somewhere above, but there will be no textual description of the WHY, i.e., no short human-readable explanation justifying the link to the parent requirement.

[haxtibal]

The difference between WHAT and HOW can be non-obvious. Take this example from current documents

3. For each memory page falling in the requested physical range
[ppos, ppos + count - 1]:
3.1. this function shall check if user space access is allowed (if
config STRICT_DEVMEM is not set, access is always granted);

Is it what, or how, or both?

Either we don't insist on separating WHAT and HOW, or we make it very clear by authoritative example what is the difference.

Otherwise I see the the danger of heating meta discussions.

[gregshue]

WHAT describes behavior of an opaque component. HOW describes the internal design/implementation.

A complete suite of verification tests should only depend on the behaviors and API specifications. IIRC, for safety critical (e.g., nuclear, avionics) it is supposed to be developed by someone without knowledge of the internals.

[haxtibal]

formal names directly is seen as too redundant and too heavy

Do you say that just the name, for example, "WHAT" instead of "STATEMENT" exempts the developer from reading guidelines?

This wouldn't work for me. If I see formalism (our keywords are formalism), the first thing I do is to look for the spec behind. I'd not try to guess what they mean, no matter if the keyword is more from native speak or more tech speak.

[gregshue]

There are multiple agents that have a stake in this. One is evaluating the suitability of this code to solve a bigger problem (e.g., product manufacturer). Another is the maintainer/contributor of this code. The terminology must serve both well. Notice that the first must evaluate the terms used across all components align in definition and concept. A software component would likely be dismissed if alignment of the definitions and concepts can't be determined quickly and easily.

I think the mapping and definitions need to be in place from the beginning.

[stanislaw]

Do you say that just the name, for example, "WHAT" instead of "STATEMENT" exempts the developer from reading guidelines?

Maybe my comment is a little misleading. What I really want to do can be very well illustrated by this excellent quote from Chuck Wolber:

The deeper problem is that there is a semantic information loss when you go from “idea in your brain” and “code that implements that idea”. Hence anyone who wants to understand your code must, to some degree, guess at the lossy part.

Even with my requirements engineering experience, I find it much more natural to think in terms of WHAT/WHY than in terms of STATEMENT/RATIONALE. Can we allow writing formal WHAT/WHYs in the source code while tracing to the as they were STATEMENT/RATIONALE when we create traceability reports?

[haxtibal]

Question on the How:

The Linux kernel already has massive amount of documentation under Documentation/ (.rst files) and inlined to source code (kernel-doc). Most is probably about how to use internal APIs, and inner concepts of core features. Does this classify as "How"? We have also examples of how-candidates inlined to source code.

How much do we want to get involved?

• Do we want to add formalism? SPDX-Req-How would add formalism.
• Do we want to introduce global convention for where to put the "how"? Always in .rst, always in functions comments, always on top of a .c file...
• Do we want to link existing documentation with our WHAT? By http URL? By parent/child IDs?

[stanislaw]

Feedback:

It was not clear from your sample file whether the statements were with a function declaration or an implementation.

[paolonig]

I appreciate the effort and the proposed improvements, however there are still a couple of points that we should address:

1. compatibility with the current kernel-doc header format
2. an example where WHY and HOW are used so that their value is clear

[paolonig]

TBH I prefer SPDX-Req-ID on top on a separate line instead of SPDX-Req-TITLE for different reasons:

1. with this format we are breaking the compatibility with the kernel-doc header format
2. if the name of the function changes, also the req title changes
3. we may have the same function name in separate files (e.g. as static functions)

[paolonig]

the above format is breaking compatibility with the kernel-doc header. You should have:

• SPDX-Req-ID
• SPDX-Req-API:
• read_mem - read from physical memory (/dev/mem).
• @file: struct file associated with /dev/mem.
• @buf: user-space buffer to copy data to.
• @count: number of bytes to read.
• @PPOS: pointer to the current file position, representing the physical

•    address to read from.
  

[haxtibal]

breaking compatibility with the kernel-doc header.

Could you explain how exactly this is breaking? Do we make syntax invalid for kdoc_parser, or do we ignore convention from Writing kernel-doc comments?

[paolonig]

For sake of compatibility with the kerne-doc header this SPDX-WHAT should be in between of the prototype definition and the context definition

[paolonig]

This is what I was mostly struggling to figure out....i.e. why we would need a "WHY" field....usually the WHY is described in the commit log, not in the requirements

[paolonig]

TBH for a pre-existing code, like linux, for the HOW we could just look at the code....