Repository navigation
docs: Add versioned links #314
Description
For versioning requirements, it was agreed that we will try the 'Hash calculation' approach.
What should it do?
- Calculate a hash for each requirement based on certain attributes of said requirement. Attributes so far selected: ("id", "title", "content", "reqtype", "security", "status".)
- Find all links to current requirement and populate the linked requirements hashes too.
- Implement warnings that run during build & incremental that will warn the user if a hash of a requirement that it depends on has changed and show the appropriate method of fixing it.
- Have an 'overwrite' option that allows for overwriting 'linked-hashes' values to bring them back up to harmony with changed requirements.
Current Progress:
There is an MVP in the works, that implements this as a Builder, this way it can be specified as a seperate 'bazel run //docs:hash_calc_build` command or similar, and there is no 'accidental' usage of it, which might be the case if we would add it to a 'docs:incremental' or similar command as an option.
A 'finished' requirements then might looks something like this:
.. feat_req:: input
:id: FEAT_REQ__TESTING
:own_hash: 06bb68
:linked_hashes: STKH_REQ__8[aa506c], STKH_REQ__9[d82c1c], STKH_REQ__20[68a015], STKH_REQ__30[0ddffe]
:reqtype: Functional
:security: YES
:safety: ASIL_B
:satisfies: STKH_REQ__8, STKH_REQ__9, STKH_REQ__20, STKH_REQ__30
:status: valid
This is a TEST feature, and this is it's content.Here own_hash as well as linked_hashes are populated automatically, and have not to be touched manually.
Since the underlying RST file will be changed, it should be made sure that the user understands this clearly and is okay with doing so.
Activity
AlexanderLanin commentedon Feb 25, 2025
to be discussed: is status really hash relevant? Will it not be covered by status-check?
MaximilianSoerenPollak commentedon Mar 25, 2025
More Info:
Verify links/hashes
on request / on tag -> ERROR
otherwise -> WARN
Discuss with process team whether we have DRAFT requirements in the module (no link verification)
MaximilianSoerenPollak commentedon Mar 25, 2025
What is missing:
verification of linked requirements.
adapt to warning level
probably more too.
9 remaining items
FScholPer commentedon Oct 8, 2025
The thing is that at least for feature requirements and stakeholder requirements we need also a check if there is that milestone version and the tree should then be buildable only for the milestone version. If we have these mechnisms anywhere we could reuse them there also. Just as an idea
dcalavrezo-qorix commentedon Nov 27, 2025
Hi @MaximilianSoerenPollak,
Is this issue still relevant? If not, please add the
trashlabel so it can be marked for deletion.MaximilianSoerenPollak commentedon Mar 18, 2026
According to newest information Useblocks is working on this still and soon will have a working version we can check out
AlexanderLanin commentedon Jun 10, 2026
version attribute is now available for all needs