Define "Feature Request" terminology

[mmccool]

Proposal for process in meeting on Oct 9 was as follows:

• Separate use cases and feature requests.
• Feature requests can be in the form of user stories, and link a feature to a purpose.
• The purpose can be a single use case or a category of use cases (e.g. use cases needing efficiency).
• If accepted, a feature request becomes a requirement.

It would be good to create clear definitions of these terms, e.g. "Feature Request" (and use case, and requirement, and category). Will do so in the discussion part of this issue (or maybe make a PR for an MD file...).

See also:

• https://github.com/w3c/transitions/issues/new?assignees=plehegar&labels=Awaiting+Team+Verification%2C+Entering+CR&projects=&template=6.3.07-candidate-recommendation.md&title=CR+Request+for+%3Ctitle%3E+-+%3Cspecification+shortname%3E
• https://www.w3.org/policies/process/#transition-cr

[relu91]

I'm totally in favor of this new definition of streamlining "developer-oriented" requests. About "If accepted, a feature request becomes a requirement" I think it might be useful to have "acceptance criteria" as a field in the Feature Request proposal to extract actionable requirements because sometimes it might not be obvious from the user story.

In the end, we could have this simple template:

[Title]

As a [user type/persona], I [want to], [so that].

Use cases

• [Link to use case]
• [Short description of a range of use cases]

Acceptance criteria - optional

• Given [ some precondition]
• When [ some action or event occur ]
• Then [ some expected outcome ]

One thing that we might have to do is to prepare a list of readable personas or user-types (but the issuer might add new user types or personas if they want).

[mmccool]

This may also be useful: IEEE SWEBOK, contains definitions and references for requirements: https://ieeecs-media.computer.org/media/education/swebok/swebok-v4.pdf

The definition of "requirement" in particular is helpful:

1. a condition or capability needed by a user
   to solve a problem or achieve an objective;
2. 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

Note that 1 corresponds to the elements of a user story; user, capability, objective; however there is another interpretation for a "condition" possessed by a system to satisfy a standard that we need also to deal with (but... standards bodies can be stakeholders/personas).

[mmccool]

I'm totally in favor of this new definition of streamlining "developer-oriented" requests. About "If accepted, a feature request becomes a requirement" I think it might be useful to have "acceptance criteria" as a field in the Feature Request proposal to extract actionable requirements because sometimes it might not be obvious from the user story.

In the end, we could have this simple template:

[Title]

As a [user type/persona], I [want to], [so that].

Use cases

• [Link to use case]
• [Short description of a range of use cases]

Acceptance criteria - optional

• Given [ some precondition]
• When [ some action or event occur ]
• Then [ some expected outcome ]

One thing that we might have to do is to prepare a list of readable personas or user-types (but the issuer might add new user types or personas if they want).

Yes, that looks good. Might also want an optional "details" field to allow people to elaborate on the user story if necessary. To avoid confusion we could also just call "feature request" a "proposed requirement".

Next step: let me see if I can capture the above in an MD file. Later on we may want a YAML file. I think the idea of an acceptance criteria is ok but we don't necessarily need all the detail.

[mmccool]

It's possible this is a different thing than a "User Story". Basically this would be a mechanism for an external stakeholder to request a feature, that if accepted, would TURN INTO a userstory-requirement. But in the short term we should probably focus on internally-generated user stories, i.e. documenting the motivations for internal work already in progress.

[mmccool]

We have now defined a new process based on user stories. The template does not include acceptance criteria but I think that is for the accepter to define, not the submitter... so I'd like to close this issue. @relu91 do you agree?

[relu91]

Yes, we can close this issue because the main question should be already covered in the new process.

The template does not include acceptance criteria but I think that is for the accepter to define, not the submitter...

I agree on some degree, but sometimes even the submiter can use them to add additional information about the user story he/she is trying to propose. Probably that would be part of the issue discussion, so we could make them optional. We can for now forget about it and see if it makes sense to introduce them once we have gathered some experience with user stories and the whole process.