Change Impact analysis tool

[aschemmel-tech]

Goal:

• Implement the process requirement https://eclipse-score.github.io/process_description/main/process_areas/change_management/guidance/change_management_reqs.html#gd_req__change_tool_impact_analysis
• Proposal for a solution for this was docs: Add versioned links docs-as-code#314

Stakeholders:

• marco.heinemann@useblocks.com - contacted by @aschemmel-tech about the addition of a sphinx needs attribute to document the version of a needs element (to be able to link like "need_id@version") - solution implemented by UseBlocks: https://sphinx-needs.readthedocs.io/en/stable/changelog.html#release-8-0-0
• @masc2023 as the "process owner" of the change management process

[arnoox]

Preview of Versioned Links in Sphinx-Needs

The Sphinx-Needs maintainers have been actively working on this feature. Here is a concrete preview of how it will look and feel from a user perspective.

"Versioned links" allows to attach a filter expression or a hash to a link, so Sphinx-Needs can verify at build time that the target need still satisfies your expectation, e.g. that it hasn't changed since it was reviewed.

---

Option A: Manual versioning with a version field

1. Configure the field in ubproject.toml / conf.py:

[needs.fields.version]
schema.type = "integer"   # or "string" / "float"
nullable = false           # every need must carry a version

2. Set a version on your needs:

.. req:: My Requirement
   :id: REQ-001
   :version: 42

3. Link to a specific version:

.. spec:: My Specification
   :id: SPEC-001
   :links: REQ-001[version==42]

At build time, Sphinx-Needs checks that REQ-001 currently has version=42. If the requirement was bumped to version: 43, the build reports a broken constrained link.

Note: later semantic versioning could be supported

---

Option B: Automatic hash-based versioning

For projects that want zero-maintenance pinning, a built-in hash dynamic function will compute a fingerprint of the need's content automatically:

[needs.fields.hash]
default = "[[hash(id, title, description)]]"
fixed = true             # cannot be overridden per-need
function_priority = 1000 # runs last, after all other fields are resolved

Linking by hash:

.. spec:: My Specification
   :id: SPEC-001
   :links: REQ-001[hash=="a3f5c2d1"]

The hash is recomputed on every build. If REQ-001 changes (even a typo), the hash changes and the constrained link fails, giving a precise "the thing I linked to has changed" signal, but this could also get annoying ;-)

---

Syntax overview

The new link constraint syntax is ADDRESS[<filter expression>], using the same filter/query syntax already familiar to Sphinx-Needs users (field=="value", field>5, and / or, etc.):

:links: REQ-001[version==42]
:links: REQ-001[version>=40 and status=="accepted"]
:links: REQ-001[hash=="a3f5c2d1"]

Mixed usage with existing link syntaxes is fully supported:

.. req:: My Requirement
   :id: REQ-002
   :links:
     REQ-001[version==42],
     <<alias: OTHER-REQ-003>>,
     [[dynamic_func()]]

---

Note: field names are fully configurable

version and hash are just the names used in the examples above, they are regular Sphinx-Needs fields and can be named anything. Projects that prefer shorter link syntax could use single-letter names:

[needs.fields.v]
schema.type = "integer"

[needs.fields.h]
default = "[[hash(id, title, content)]]"
fixed = true

Which then allows very compact links:

:links: REQ-001[v==42]
:links: REQ-001[h=="a3f5c2d1"]

There is also the idea of introducing a shorthand field configuration to make the common cases even less verbose to set up. Instead of writing out the full field config, something like:

[needs.fields.version]
shorthand = "v"