Ways to implement Gilb's Planguage in Sphinx Needs: qualifiers and quality levels

[HughG]

Hi folks, I'm a principal engineer who went to a training course by Tom Gilb about 10 years ago, and have been vaguely hoping for free-ish tooling to enable us to use Planguage for requirements -- rather than the mish-mash of poorly-organised Confluence pages and after-the-fact design docs we have now. Sphinx-Needs could well be it, specially given the VSCode extension, so thanks for this fantastic set of tools :-)

The basics of the Planguage fit Sphinx-Needs nicely, but a couple of things are more tricky. I'm trying to figure out how I might implement them, and whether it would need changes to Sphinx-Needs, or custom directives, filter functions, or what. This is not a clear-cut question, rather I'm looking for inspiration for design/implementation approaches.

Levels

Quality Requirements in Planguage are requirements on scalar values related to a particular function, e.g., latency. They have a Unit, a Meter (statement of how you can measure them), and a value for some/all of a set Levels. There's a set of logical levels defined by default (e.g., Past, Survival, Wish, Goal) but a given project could add its own.

Maybe these could be need-parts within a need (option value or content), where the part-id is the level name, and the part content is the value. Or maybe some custom inline role within an (option value or content)? However, I'm not sure how I'd apply Qualifiers -- see next.

Qualifiers

One or more Qualifiers can be attached to a various things: a requirement (to qualify the entire requirement), a level (to state that the Goal Level for a Quality Requirement is different in different releases, deployments, market segments, etc.), a link (e.g., to state that a function only has some particular sub-function or quality requirement in certain deployments etc.), and maybe other things.

Qualifiers can be expressed as inline shorthand (a conjunction of boolean expressions) or by reference to a separate defined document entry with its own ID (so, in Sphinx-Needs, a custom type of need).

That sounds sort-of like a blend of variants and filter functions, and/or possibly use of needextend to replace the Level values for a Quality Requirement (if it were possible to apply needextend conditionally). However, my (very inexperienced) assumption about how qualifiers should appear in rendered documents is that we ought to see all of the qualified alternative values, rather than only the ones which are currently "selected" by some build process. That allows you to, e.g., look at the spec for a function and realise that it also needs to have some kind of build-time or runtime config, because it needs to be on/off in different deployments. (It might also be nice to be able to build the same doc with some set of qualifiers "baked in", as with the way variants are applied just now in Sphinx-Needs (1.3.0) but that's not the main idea).

[danwos]

He @HughG,
Tough question, but I like them :)
I hopefully have understood the most important points here. Let's see.

Levels

Levels sound for me like additional options. As it looks like the possible level names are always the same:

.. req:: My Planguage requirement
   :id: REQ_001
   :wish: 20
   :fail: 10
   :past: 12
   :trend: 15

   A requirement with levels

Would you like to do something with these levels?
For instance, reference them, recalculate, ...

Via templates, you can also add them to the representation of the content and add units and other information, so that they may become more meaningful.

Qualifiers

I agree that a feature to see all available variants would be nice.
I discussed this with some other users as well in the past and have some ideas in mind. But no time to implement something in this direction.

However, I have never seen something like your Qualifiers in docs. But I like the idea behind it.
And if I understood them correctly, they are something like programmatic statements, which have access to global variables for comparison.
The statement itself needs to be written into the representation.
Right now, I have no idea when the statement result gets calculated and what shall happen with it.

It feels a little bit like the filter-strings, which are also statements and get executed in the context of a need and can have access also to globally defined values. If the statement is True, then the need is added to the filter-result.
So maybe a Sphinx-Needs option should be able to store such a Python statement.
And the representation is a combination of result and statement::

# Pseudo representation text (should be an image in a perfect world ;) )

Requirement: Reach 200 new customers till end 2023
id: REQ_123
status: open
reached: True (new_customers_2023 >=200)

Some content

The statement could be any Python code. So it will be quite powerful, but not so structured as the given example in Qualifiers

But for sure, it would be a new feature for Sphinx-Needs.

Does this also already goes in the right direction?

[HughG]

Hi @danwos, apologies for the very-belated reply. I haven't had much time to work on this for ages, and in fact I've started looking into https://logseq.com/ as maybe a more suitable tool for what I want to do, if I can get enough structured querying to work within it.

That said, your point about levels is a good insight. I had been thinking of them as nested things because that's how they're typically presented. But there is at most one value for each per need, so in terms of the data model they're just optional options.

I also think your idea for how to implement Qualifiers sounds good, though who knows if/when you'd prioritise implementing it :-)