Proposed Requirements Policy by mmccool · Pull Request #1229 · w3c/wot

mmccool · 2025-04-25T19:47:14Z

A proposed policy defining a process to use User Stories to document requirements. The process also defines how to manage and update requirements in the Use Case and Requirements document with TF or WG approval as appropriate.

benfrancis

I would like to suggest a requirements document for each specification, derived from top level use cases. I think this would make it more clear which specification is intended to fulfil each requirement, and provide a set of requirements for each specification to be tested against to determine when it is complete. See w3c/wot-usecases#361

benfrancis · 2025-04-28T15:16:32Z

policies/requirements.md

+are published we should be able to  specify exactly what problem each new feature
+(or change to an existing feature) is solving.
+
+The following requirements capture process is centered on User Stories, which link Use Cases to Features


How exactly are Use Cases & User Stories meant to be used together? When should someone use one or the other and what is the relationship between the two?

Also see w3c/wot-thing-description#2098

See also: w3c/wot-usecases#358

Suggested change

The following requirements capture process is centered on User Stories, which link Use Cases to Features

The following process of requirement capture is centered on User Stories, which link Use Cases to Features

TallTed

Language, markup, and such.

TallTed · 2025-06-06T18:27:40Z

policies/requirements.md

+
+## Requirements 
+New WoT specification Features should be motivated by Use Cases, as when updated specifications
+are published we should be able to  specify exactly what problem each new feature


Suggested change

are published we should be able to specify exactly what problem each new feature

are published we should be able to specify exactly what problem each new feature

TallTed · 2025-06-06T18:28:15Z

policies/requirements.md

+are published we should be able to  specify exactly what problem each new feature
+(or change to an existing feature) is solving.
+
+The following requirements capture process is centered on User Stories, which link Use Cases to Features


Suggested change

The following requirements capture process is centered on User Stories, which link Use Cases to Features

The following process of requirement capture is centered on User Stories, which link Use Cases to Features

TallTed · 2025-06-06T18:29:50Z

policies/requirements.md

+User Stories and Use Cases
+will be captured in the [Web of Things (WoT) Use Cases and Requirements](https://w3c.github.io/wot-usecases/) document.
+As a general principle the Use Case TF is tasked with managing only the *form* of
+the document and the *process* of adding new Use Cases and User Stories but not with specifying the 


Suggested change

the document and the *process* of adding new Use Cases and User Stories but not with specifying the

the document and the *process* of adding new Use Cases and User Stories, and _not_ with specifying the

TallTed · 2025-06-06T18:31:46Z

policies/requirements.md

+1. A TF develops User Stories internally, as well as any supporting documentation such as a detailed 
+   design or technical requirements.
+   See the [TD TF suggested process](https://github.com/w3c/wot-usecases/blob/main/tf-issue-process.md).
+   Detailed design or technical requirements will generally *not* be captured in the 
+   WoT Use Case and Requirements document.
+   The Use Case and Requirements document is only meant to 
+   capture a high-level summary of the motivation for each Feature by linking it to one or more Use Cases.


Suggested change

1. A TF develops User Stories internally, as well as any supporting documentation such as a detailed

design or technical requirements.

See the [TD TF suggested process](https://github.com/w3c/wot-usecases/blob/main/tf-issue-process.md).

Detailed design or technical requirements will generally *not* be captured in the

WoT Use Case and Requirements document.

The Use Case and Requirements document is only meant to

capture a high-level summary of the motivation for each Feature by linking it to one or more Use Cases.

1. A TF internally develops User Stories, as well as any supporting documentation such as a detailed

design or set of technical requirements.

See the [TD TF suggested process](https://github.com/w3c/wot-usecases/blob/main/tf-issue-process.md).

Detailed designs or technical requirements will generally *not* be captured in the

WoT Use Cases and Requirements document.

The Use Cases and Requirements document is only meant to

capture a high-level summary of the motivation for each Feature by linking it to one or more Use Cases.

TallTed · 2025-06-06T18:32:26Z

policies/requirements.md

+3. The TF proposes User Stories using the Use Case TF’s User Story issue template, one issue per User Story.
+   A User Story links Use Cases to Features (or Work Items, if the work is still in progress).  
+   A Feature can be defined by an individual assertion or a normative section of a specification.


Suggested change

3. The TF proposes User Stories using the Use Case TF’s User Story issue template, one issue per User Story.

A User Story links Use Cases to Features (or Work Items, if the work is still in progress).

A Feature can be defined by an individual assertion or a normative section of a specification.

2. The TF proposes User Stories using the Use Case TF’s User Story issue template, one issue per User Story.

A User Story links Use Cases to Features (or Work Items, if the work is still in progress).

A Feature can be defined by an individual assertion or a normative section of a specification.

TallTed · 2025-06-06T18:37:12Z

policies/requirements.md

+4. The Use Case TF Creates a PR based on content in the submitted User Story, Use Case, or Use Case Category issue(s).
+   This PR converts the issue to a HTML form to update the Use Case and Requirements document.  The Use Case TF
+   does *not* merge the PR at this point, but leave it open to solicit comments.  Each such PRs is linked to the
+   related issue.


Suggested change

4. The Use Case TF Creates a PR based on content in the submitted User Story, Use Case, or Use Case Category issue(s).

This PR converts the issue to a HTML form to update the Use Case and Requirements document. The Use Case TF

does *not* merge the PR at this point, but leave it open to solicit comments. Each such PRs is linked to the

related issue.

5. The Use Case TF Creates a PR based on content in the submitted User Story, Use Case, or Use Case Category issue(s).

This PR converts the issue to an HTML form to update the Use Cases and Requirements document. The Use Case TF

does *not* merge the PR at this point, but leaves it open to solicit comment. Each such PR is linked to the

related issue.

TallTed · 2025-06-06T18:37:24Z

policies/requirements.md

+   This PR converts the issue to a HTML form to update the Use Case and Requirements document.  The Use Case TF
+   does *not* merge the PR at this point, but leave it open to solicit comments.  Each such PRs is linked to the
+   related issue.
+6. The HTML form and rendering for each PR is reviewed by the original submitters of the related issue.


Suggested change

6. The HTML form and rendering for each PR is reviewed by the original submitters of the related issue.

6. The HTML form and rendering of each PR is reviewed by the original submitters of the related issue.

TallTed · 2025-06-06T18:39:20Z

policies/requirements.md

+7. Once both the original submitters and the Use Case TF approve, the PR may be merged.  In the case of a User Story,
+   approval must be in the form of a formal Resolution by the proposing TF, as long as the User Story only impacts
+   the deliverable that TF has responsibility for.  In all other cases, including TF's proposing User Stories that
+   impact deliverables of other TFs, in addition to the original submitters and the
+   Use Case TF approving the submission, a formal Resolution by the entire WG is required before a new User Story can be merged.
+   However, PRs for Use Cases and Use Case Categories can be merged at the discretion of the Use Case TF as long as the original
+   submitters also agree.


Suggested change

7. Once both the original submitters and the Use Case TF approve, the PR may be merged. In the case of a User Story,

approval must be in the form of a formal Resolution by the proposing TF, as long as the User Story only impacts

the deliverable that TF has responsibility for. In all other cases, including TF's proposing User Stories that

impact deliverables of other TFs, in addition to the original submitters and the

Use Case TF approving the submission, a formal Resolution by the entire WG is required before a new User Story can be merged.

However, PRs for Use Cases and Use Case Categories can be merged at the discretion of the Use Case TF as long as the original

submitters also agree.

7. Once both the original submitters and the Use Case TF approve, the PR may be merged. In the case of a User Story,

approval must be in the form of a formal Resolution by the proposing TF, as long as the User Story only impacts

the deliverable for which that TF has responsibility. In all other cases, including TF's proposing User Stories that

impact deliverables of other TFs, in addition to approval by the original submitters and the

Use Case TF, a formal Resolution by the entire WG is required before a new User Story can be merged.

However, PRs for Use Cases and Use Case Categories can be merged at the discretion of the Use Case TF, as long as the original

submitters also agree.

TallTed · 2025-06-06T18:41:32Z

policies/requirements.md

+9. The Use Case TF will publishes updates to the WoT Use Case and Requirements document as a W3C Note periodically,
+   and in particular if there are any changes to the document, at the end of each charter period.


Suggested change

9. The Use Case TF will publishes updates to the WoT Use Case and Requirements document as a W3C Note periodically,

and in particular if there are any changes to the document, at the end of each charter period.

9. The Use Case TF will periodically

— particularly, if there have been any changes to the document, at the end of each charter period —

publish updates to the WoT Use Cases and Requirements document as a W3C Note.

TallTed · 2025-06-06T18:41:44Z

policies/requirements.md

+9. The Use Case TF will publishes updates to the WoT Use Case and Requirements document as a W3C Note periodically,
+   and in particular if there are any changes to the document, at the end of each charter period.
+
+There are some additional details in the Use Case TF repo's [README](https://github.com/w3c/wot-usecases)


Suggested change

There are some additional details in the Use Case TF repo's [README](https://github.com/w3c/wot-usecases)

There are some additional details in the Use Case TF repo's [README](https://github.com/w3c/wot-usecases).

mmccool added 3 commits April 25, 2025 16:47

Proposed Requirements Policy

7e5667f

A proposed policy defining a process to use User Stories to document requirements. The process also defines how to manage and update requirements in the Use Case and Requirements document with TF or WG approval as appropriate.

Update requirements.md

02a2c5a

Update requirements.md

494c7af

mmccool mentioned this pull request Apr 25, 2025

Update README.md - IP rules for non-members w3c/wot-usecases#355

Open

benfrancis mentioned this pull request Apr 28, 2025

Simplify the user story template w3c/wot-usecases#360

Open

benfrancis reviewed Apr 28, 2025

View reviewed changes

TallTed suggested changes Jun 6, 2025

View reviewed changes

	The following requirements capture process is centered on User Stories, which link Use Cases to Features
	The following process of requirement capture is centered on User Stories, which link Use Cases to Features

	are published we should be able to specify exactly what problem each new feature
	are published we should be able to specify exactly what problem each new feature

	the document and the process of adding new Use Cases and User Stories but not with specifying the
	the document and the process of adding new Use Cases and User Stories, and _not_ with specifying the

	6. The HTML form and rendering for each PR is reviewed by the original submitters of the related issue.
	6. The HTML form and rendering of each PR is reviewed by the original submitters of the related issue.

		9. The Use Case TF will publishes updates to the WoT Use Case and Requirements document as a W3C Note periodically,
		and in particular if there are any changes to the document, at the end of each charter period.

-. The Use Case TF will publishes updates to the WoT Use Case and Requirements document as a W3C Note periodically,
-   and in particular if there are any changes to the document, at the end of each charter period.
+. The Use Case TF will periodically
+   — particularly, if there have been any changes to the document, at the end of each charter period —
+   publish updates to the WoT Use Cases and Requirements document as a W3C Note.

	There are some additional details in the Use Case TF repo's [README](https://github.com/w3c/wot-usecases)
	There are some additional details in the Use Case TF repo's [README](https://github.com/w3c/wot-usecases).

Conversation

mmccool commented Apr 25, 2025

Uh oh!

benfrancis left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TallTed left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants