How to work with "universal" requirements?

[InAnYan]

Dislaimer: I don't have a solid background in requirement tracing.

The typical use case of OFT is to write 1 requirement and link 1 place of code that implements this requirement.

However, I often see that people create requirements like: All fetchers should handle 404 errors and return empty results, which is a universal statement. However, it cannot be handled really, because if someone links at least one fetcher A, then the requirement will be considered as covered, even though, fetchers B/C/D might not implement it.

So, my questions are:

1. What should a developer do in this place? Are there any techniques?
2. Or maybe it is a mistake to define such requirements?

[InAnYan]

I asked the question to Gemini Pro, and here is what he proposed:

(Continuing my example of fetchers)

1. Write some piece of utility code that all fetchers will use, and link the requirement to that one common piece of code. Or extend from an abstract class that hanldes the requirement. -- I think it's a solution, but this way we can't guarantee that a fetcher will use this common piece of code
2. Delegate it to some other piece of code or tool. E.g. a CI/CD check, or other analyzer, and then "link" this analyzer to the requirement. (e.g. all user-facing text should support localization, then link it to some testing suite)
3. Decompose the requirement: so for a universal requirement req make req-A, req-B, req-C, etc. -- Super tedious, but this is exactly what needs to be

[MentorFilou]

1. is a good approach for your case as long its not critical; tho it kind of breaks exactly the requirements traceability that is delivered by a tool like OFT
2. thats a workaround but for some cases might actually be needed to ensure all new things of some kind are automatically checked by it
3. bloats the artifact set which in my opinion is bad. - read my answer below for details

[MentorFilou]

I was facing a similiar issue when creating my own requirements tracing suite flashtrace, here is how I am handling it there. My approach is that instead of relying on artifact types alone, one could optionally specify the explicit needs for a requirement instead of a generative need of some artifact type. That means you can write Need: impl:item-name, impl:item-name-2 (which in OFT would be something like Need: impl~item-name, impl~item-name-2, but it isnt currently allowed).

As this would be scaling bad, you could use grouping, meaning the name of a specification item can be written as some-group/more-nested-groups/item-name. So your needs list could be Needs: impl:fetcher-group/place-one, impl:fetcher-group/place-one, .... It doesn't scale well on your case tho. My case was rather a multi (but constant) layer development, e.g. in APIs where you'd have one route, one service, one repository which are all needed and go as the 3 needs.

This is similar to your approach 3 above, but instead of bloating the artifact set, essentially polluting it and making it less identifiable, it scales on the name by using groups. But it admittedly makes the Needs keyword more cluttered, tho I think in your case its logically the only way if you really wanna ensure strict linkage between the requirement and all fetchers.

Feel free to remove the comment or ask me to rewrite it if you don't like me mentioning a "competitor" here..

[kaklakariada]

Hi @MentorFilou, I would be interested in your motivation to create flashtrace. Didn't you know about OFT or are there missing features in OFT?

[InAnYan]

I was thinking of introducting a notion of "entities" (maybe not the best name). So alongside the requirements, one would also link them to an "entity type". And then in the code you introduce new entities fetcher:a, fetcher:b, and then all requirements that are linked for the entity fetcher need to be covered for entities a, b.

I guess semantically it's the same as the 3rd approach proposed by Gemini, but the notion of entities just removes the code duplication

[MentorFilou]

That is a great extending concept. Semantically its rather bundling your fetcher as an artifact type which, by the design of free-text artifact types, works. But its not the intentional layering of those.

Let me give another proposal based on yours. I'd split your concept from the artifact identity entirely and add it as a new dimension on top. That way the identity stays clean of any functional back-application on it (e.g. needing something because in the name it reads fetcher).

Lets say you have a new requirement that is fetching something and in accordance should follow what you have specified as the "fetcher". From my perspective that is inheritence by design. By my proposal you'd have the entity as an abstract element and your new requirement explicitely stating that it inherits from this entity:

docs/reqs/entities/fetcher.md

## Fetcher Entity
`$fetcher`

This is the description of what a fetcher is. A fetcher is an abstracted requirement. It doesn't itself has to satsify anything. However, every requirement that will be entitled a fetcher will need to satisfy what a fetcher demands. Similarly to normal requirements the fetcher specifies keywords below. (Note: $ is a placeholder there)

Needs: `impl~fetcher-$`

docs/reqs/a-new-requirement.md

## Some requirement
`req~some-requi`

This is the description of a requirement.

Inherits: fetcher

Now req~some-requi needs impl~fetcher-some-requi. Obviously you could've just written out Needs: impl on some-requi directly but the way its structured here, once fetcher changes all requirements inheriting from it are informed (because they are properly connected).

That still feels a little weird because you'd have to lookup the name that you now need to comply with (e.g. how the placeholder is put) but the parser can support on this. And maybe there is a slight simplification allowing to actually skip the placeholder principle. But I cannot figure a way yet while staying compliant to artifact types.

Why care about artifact types? They create a sort of layering. Maybe an entity isn't created for the need of an impl but a utest actually. Hiding that behind a generic entity~req breaks this principle.

Admittedly that approach is advanced and applies "complex" software engineering principles (inheritence/abstraction) onto the specs that are often meant for non-technical stakeholders too... From what works now, I'd suggest to introduce an artifact type fetcher in your case. That is simple but not perfect.

Just putting my unfiltered thoughts here, sorry if its confusing.

[InAnYan]

Oh, but that's not what I really needed. There shouldn't be actually any inheritance.

And I believe it is a responsibilty f one requirement to declare all artifacts that it needs, because different requirements require different artifacts.

I was more questioning how to exactly have several requirements for several entities of the same type

[redcatbear]

Cross-cutting concerns are always a headache in requirement engineering. As soon as an "all" appears in a requirement, you know you are in for a maintenance issue.

@MentorFilou's approach to require full ids instead of just the artifact type is one that is typical. It's safe from a linking perspective.

The main issue is that it breaks the abstraction. Suddenly the abstract item learns details (IDs) of the concrete ones. And, if the document with the requirements has a different author than the code, two roles start modifying the specs.

That's why OFT only declares needed artifact types.

Also, keeping bidirectional links aligned by hand is hard.

I admit though that the one-item coverage is enough has it's own issues.

[redcatbear]

I am thinking about a feature like this to avoid coupling:

`dsn~fetchers-handle-404~1`

**All** fetchers handle a HTTP 404 safely.

Needs: impl, utest

Match tags: fetcher

In the code:

// [oft.tags: fetcher]
class LogFetcher
{
    // ...

    // [impl -> dns~fetchers-handle-404~1]
   private void handleClientErrors(final int errorCode)
   {
        // ...
    }
}

You would still need to annotate the class with the fetcher tag. But OFT could then see that something with that tag is not covered should you forget the requirement tag.

[InAnYan]

Yes! I had the same idea in mind!

I also think we need to have a label? E.g. log-fetcher? So that if one has implemented one requirement, but not second, it would be possible to track which fetcher is affected. + to allow to work cross-file

[redcatbear]

How about this:

`dsn~fetchers-handle-404~1`

**All** fetchers handle a HTTP 404 safely.

Needs: impl, utest

Match tags: `.*-fetcher.*`

In the code:

// [oft.tags: log-fetcher]
class LogFetcher
{
    // ...

    // [impl -> dns~fetchers-handle-404~1]
   private void handleClientErrors(final int errorCode)
   {
        // ...
    }
}

The regex would match all. But the message can contain the list of concrete matches.

[InAnYan]

// [impl -> dns~fetchers-handle-404~1]

But here we also need to put log-fetcher?

[redcatbear]

Not really. The way I envision this is that you would have file-scoped tags (see example above) that get merged with the tags of the individual items. It's an idea, not yet fully-fledged design.

With everything we add, we aim to keep the complexity down. Complexity is the enemy of safety. :-)

[InAnYan]

Okay, I see and agree that this is simpler. I believe this already brings advantages.

Thanks! I looking forward for a more polished design and this feature in OFT (but, of course, whenever you want it, no pressure)