id vs id_complete and need_parts

[Thomas-Swindells-t]

Hi all,

I'm struggling to understand the distinction between id and id_complete and what the intention for them are.

From what I understand looking at the code id_complete is primarily targeted at need_parts, but the filter code at least blurs this distinction and for nodes makes id_complete=id. The code seems to assume that id_complete will be in the form "." and further more need_ref makes the assumption that the parentid will not contain dots,

My confusion comes in part due to two of the features that I have been working through:

1. Allowing needflow to represent nested needs as nested containers. Currently only need_parts can be drawn this way so this change will remove a key distinction
2. Improved auto id generation. My initial plan was to make a child node id be composed as .. For deeply nested nodes this could create many dots and looks like it will require changes to need_ref.

From what I can see you already have to use id_complete to reference a needpart, the only time the distinction with the id is important is in tables or other places where the needpart is presented with its shorter i'

From some angles neep_parts pretty much look like any other nested need except with a streamlined declaration syntax and a slight distinction in filtering.

As a straw man I'd propose that id_complete isn't needed, instead the id of need_parts will be the complete id. Where a simplified id is wanted this can be calculated by taking the final segment after the last dot - this would work both with need parts and nested needs that inherit their parents name.

[danwos]

I agree that need_parts and nested needs have some common parts.
need_parts is quite older and nested needs was just born somehow by accident, as it surprisingly worked already without any code modifications.

For need_parts I like to have 2 IDs (main need and the part), as it makes filtering much easier.
Also need_part was never designed to be standalone, it must always be part of a need and gets represented like this.

For nested Needs I'm somehow open.
But here I also think that it should have its own id, which is not related to parent and which is unique in the whole documentation.
Otherwise moving a nested need out of its parent needs a modification of all links.

For me the goal of a need-definition was always, that it is not related to its location and can be easily copied and referenced without knowing any context of the documentation around the need.
The final representation can for sure have such information and maybe an additional, more complex id.

So I would stay with id and id_complete for the moment.

But I'm totally open for counter-arguments .

[Thomas-Swindells-t]

As a counter argument, I'm viewing the documentation as defining a model.
A need being a child of another need is a core element of its identity. When its defining a hard relationship, removing it from one parent and moving it to a different thing is really fundamentally changing its identity so the id should change.

The inverse scenario is that if I have two identical steps (a need) in two different sequences (the parent need) they are not the same thing and definitely should have different ids as their parent is what defines them. Currently the autogenerated ids will collide and either you have to tweak the step name slightly or start manually assigning ids.

I do totally agree that both approaches are equally valid, if you are defining requirements for instance and the parent are just a grouping mechanism, moving the requirement doesn't change its identity.

What I'm thinking of is a configuration setting which lets you pick the auto id generation function, and of course manually assigned ids always take precedence.

Whilst I dig into this further, please could you explain how/where it makes filtering easier, in particular when is just the part_id section used?

[danwos]

Ok, got your point.
I'm totally open to support any id-configuration, as long as it is configurable and not a breaking-change.
But we must be careful as I think there are some hard-coded decisions inside the code, which can not handle a different id-layout by now. E.g. if a dot is present in the id, then it gets handled as need_part (needlfow).

A use_case for filtering the part_id: In some docs the part_id also gets some pre/postfixes, which indicates if this need_part is e.g. safety relevant or belongs to a specific module. Example: logging_safety as part_id and need complete_id then breaks.logging_safety.
So we can filter for each safety relevant need_parts of a bunch of needs.

For your automated Id generation, please be sure that there is no software/hardware dependency in the calculation function.
I had some problems with this in the past.
E.g. same results on linux/windows/mac, all supported Python and Sphinx needs versions, different file encodings, ... .

For the user/writer perspective, I personal also see only disadvantages having a quite long id, if a need is nested.
Referencing a need by need_a..need_b.._need_c is extensive, if need_c could be enough.
Don't get me wrong, having this nested information somewhere (e.g. another option) is helpful, but for the writer is doesn't make fun.
Also your problem that 2 identical needs, but embedded in different other needs, must a have different, autogenerated id is more a technical problem based on the chosen concept to use autogenerated ids.
I see no hard requirement, that a need must get identified by an id which contains all the parent ids as well.

I see some other conceptional solutions, which maybe would also do the job:

• If the step-need is completely identical, define it once and use needextract to reuse it where ever it is needed.
  (Drawback. You don't get a technical model, only the sphinx-output describes the model).
• Or use links to connect step-needs and maybe a tag to assign the steps to a specific workflow.
  Also here `´needextract`` could help to get a nice, final representation of the workflow on some page.

Sphinx-Needs always had the problem to somehow fulfill the requirements of an easy and efficient usability during writing the rst-code and a technical correct and accurate model. And the focus is totally on usability. The goal is to not burden the user with technical rules, which are not needed or represented in the final documentation.

And I have the feeling that your concept may go mostly in this technical direction.
But this doesn't mean Sphinx-Needs could not support it.
It should only introduce no breaking-changes, as this may touch the usability or may force the user to modify his/her rst code to work with a newer sphinx-Needs version.

[Thomas-Swindells-t]

Thanks for your input, will consider it as the design progresses.

In general if people want to directly reference a need then I'd assume they'd explicitly assign an id to it. Currently referencing needs by their autogenerated id is not fun for writers and prone to break if the title/contents of the need is edited slightly.

The main use-case I see for autogenerated needs are in the scenarios that you don't need to explicitly reference it, e.g. if it will generally be used via need table/flow/sequence etc.

With a more structured autogenerated id then at least it gives the writers more indication of what the link is if they do decide to use it, but on the whole I'd hope they didn't. It will also mean by default every need will get a unique (and fairly stable) id. I found the current scheme of hashing the title to be a big challenge as it meant there was a technical rule requiring modification of the document - deliberately changing wording to make them none-unique, or having to explicitly assign id's when I wasn't planning to reference the thing. My hope is my goal moves writing needs more towards usability as the writer won't have to worry about whether there will be a conflict with autogenerated ids.

But I certainly agree about backwards compatibility, it will definitely be a configuration option to select the generator - as anybody who is currently using autogenerated ids in references really won't appreciate them being changed.