Template for requirements

[hzbarcea]

No description provided.

[csarven]

It seems there may be some confusion about the intent of this task, so I'd like to clarify a few points.

It's considered good practice to reference the issue or action that a PR addresses. This helps others understand the context and purpose of the PR, improves record-keeping, and clearly distinguishes related or alternative solutions.

For example, assuming this PR is a follow-up to an action from the LWS WG 2025-01-27 meeting, it should state something like:

"Resolves ACTION to define a requirements template for the lws-ucs repository."

If that's the intention, I don't believe this PR aligns with the ACTION's goal. The template proposed here resembles a template for conformance clauses in a specification, which differs from a template to help derive functional and non-functional requirements from use cases - what the ACTION is meant to address.

(This ACTION arose because issues referenced in #117 presented requirements framed as use cases without linking back to the actual use cases.)

Solution-centric references have no place in a UCR document.

Ensure that functional/non-functional requirements are traceable back to their corresponding use cases. Requirements in a specification respond to these, with conformance clauses representing possible solutions - there can be multiple solutions to the same requirements in a UCR document.

For reference, see:

• https://www.w3.org/TR/ldp-ucr/
• https://www.w3.org/TR/did-use-cases/
• https://solid.github.io/notifications-panel/notifications-ucr (focus on the structure, not the content)
• ...

Note how the last two include a Requirements Matrix for clarity.

[hzbarcea]

Thanks for your thoughts @csarven. I am aware of the documents you link, I reviewed them last year. Out of all three, I like ldp-ucr, the most. But even that uses the term "shall" in the requirements extensively and pretty much follows the format I chose. I struggled a bit with with the term "component" and I was sure somebody will come up with a better phrasing. I am looking forward to the conversations in the group to best decide how to phrase this and everything will flow from there.

I also liked the dependency diagram in did-use-cases and plan to incorporate something like that in this doc.

[pchampin]

The template proposed here resembles a template for conformance clauses in a specification, which differs from a template to help derive functional and non-functional requirements from use cases

+1

Out of all three, I like ldp-ucr, the most. But even that uses the term "shall" in the requirements extensively

the LDP-UCR document uses the term "shall" indeed, but without any reference to [RFC2119]. It is used in lowercase, and not contrasted with must / should / may ...

[w3cbot]

This was discussed during the #lws meeting on 17 February 2025.

View the transcript

Template for requirements (w3c/lws-ucs#119)

laurens: There has been some discussions on this PR already.
… csarven, you made some comments. Do you want to develop?

csarven: I don't have anything to add. pchampin's suggestions on the PR are good.
… They are pending response by Hadrian. Review from others would be good.

laurens: agreed; everyone is encouraged to give feedback on this PR.

---