Skip to content

feat: change mandatory 'fulfils' to optional #669

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
RolandJentschETAS merged 6 commits into from
Jul 30, 2026
+54 −22
Merged

feat: change mandatory 'fulfils' to optional #669

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5f47fe6
change mandatory to optional links
RolandJentschETAS Jul 28, 2026
31e69ba
Merge branch 'main' into improvement_optional_arc_links
AlexanderLanin Jul 28, 2026
56d2172
Merge branch 'main' into improvement_optional_arc_links
RolandJentschETAS Jul 28, 2026
ce38c53
fix review findings
RolandJentschETAS Jul 29, 2026
8590090
extent table with link type
RolandJentschETAS Jul 29, 2026
c07e9cf
Address review: reword fulfils rule and add optional-link tests
RolandJentschETAS Jul 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 18 additions & 16 deletions docs/internals/requirements/requirements.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -546,45 +546,47 @@ Architecture Attributes
🔗 Linkage
------------------------

.. tool_req:: Mandatory Architecture Attribute: fulfils
.. tool_req:: Architecture fulfils linkage rules
:id: tool_req__docs_arch_link_fulfils
:tags: Architecture
:implemented: YES
:version: 2
:version: 3
:satisfies:
gd_req__arch_linkage_requirement_type[version==1],
gd_req__arch_attr_fulfils[version==1],
gd_req__arch_traceability[version==1],
gd_req__req_linkage_fulfill[version==1],
:parent_covered: YES

Docs-as-Code shall enforce that linking via the ``fulfils`` attribute follows defined rules.
Docs-as-Code shall allow or enforce where necessary that linking via the ``fulfils``
attribute follows the defined rules.

Allowed source and target combinations are defined in the following table:

.. table::
:widths: auto

==================================== ==========================================
Link Source Allowed Link Target
==================================== ==========================================
feat_arc_sta feat_req, aou_req
feat_arc_dyn feat_req
logic_arc_int feat_req
comp_arc_sta comp_req, aou_req
comp_arc_dyn comp_req
real_arc_int comp_req
==================================== ==========================================
==================================== ========================================== ==============
Link Source Allowed Link Target Optional/Mandatory
==================================== ========================================== ==============
feat_arc_sta feat_req Optional
feat_arc_dyn feat_req Optional
logic_arc_int feat_req Optional
comp_arc_sta comp_req Optional
comp_arc_dyn comp_req Optional
real_arc_int comp_req Optional
==================================== ========================================== ==============

.. tool_req:: Architecture fulfils linkage to AoU
:id: tool_req__docs_arch_link_fulfils_aou
:implemented: YES
:version: 1
:version: 3
:satisfies: gd_req__arch_attr_fulfils_aou[version==1]
:parent_covered: YES

Architectural static views (feat_arc_sta, comp_arc_sta)
link to Assumptions of Use (aou_req) via the ``fulfils`` attribute.
Architectural static views (feat_arc_sta) and the component itself (comp)
may link to Assumptions of Use (aou_req) via the ``fulfils`` attribute.
When such a link is present, Docs-as-Code shall restrict its target to aou_req.

@MaximilianSoerenPollak MaximilianSoerenPollak Jul 29, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sentence above already includes this stipulation

Suggested change
When such a link is present, Docs-as-Code shall restrict its target to aou_req.

@RolandJentschETAS RolandJentschETAS Jul 29, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done — removed the redundant sentence; the reworded sentence above now covers it. Addressed in c07e9cf.


.. tool_req:: Check Architecture linkage to AoU
:id: tool_req__docs_arch_link_aou_check
Expand Down
17 changes: 11 additions & 6 deletions src/extensions/score_metamodel/metamodel.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -430,10 +430,11 @@ needs_types:
mandatory_links:
# req-Id: tool_req__docs_arch_links
includes: logic_arc_int, logic_arc_int_op
# req-Id: tool_req__docs_arch_link_fulfils, tool_req__docs_arch_link_fulfils_aou
fulfils: feat_req, aou_req
# req-Id: tool_req__docs_arch_links
belongs_to: feat # make it mandatory for evaluation
optional_links:
# req-Id: tool_req__docs_arch_link_fulfils, tool_req__docs_arch_link_fulfils_aou
fulfils: feat_req, aou_req

@AlexanderLanin AlexanderLanin Jul 28, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tool_req__docs_arch_link_fulfils is titled “Mandatory Architecture Attribute: fulfils” and is marked implemented. tool_req__docs_arch_link_fulfils_aou also requires static views to link to an AoU through fulfils. Making this optional permits a feat_arc_sta without any requirement/AoU trace. The same issue applies to the corresponding comp_arc_sta change below.

Please keep fulfils mandatory, or update the tool requirements and their qualification/status as part of this PR.

generated by Codex running GPT 5.6 Terra

@AlexanderLanin AlexanderLanin Jul 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Concrete remediation proposal:

  1. Keep the existing ID tool_req__docs_arch_link_fulfils, but bump its version from 2 to 3 and update its title/text to reflect the corrected process semantics, for example:
    • Title: “Architecture fulfils linkage rules”
    • Text: “Docs-as-Code shall permit fulfils to be omitted for feat_arc_sta and comp_arc_sta. When fulfils is present, Docs-as-Code shall restrict its target to the source/target combinations in the table below.”
      The existing allowed-combinations table can remain.
  2. Update tool_req__docs_arch_link_fulfils_aou as a new version as well: replace “static views link to” with wording that permits, rather than requires, fulfils links to aou_req.
  3. Keep the metamodel requirement references, now referring to the revised requirement versions, and add tests for an unlinked static view (accepted) and an invalid fulfils target (rejected).
  4. If non-QM architecture must still trace to a same-safety requirement, retain that separately as a conditional graph check; making fulfils optional must not bypass it.

A version bump preserves the requirement ID and its traceability history while making the changed semantics explicit.

generated by Codex running GPT 5.6 Terra

@RolandJentschETAS RolandJentschETAS Jul 29, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the detailed proposal. The tool requirements have been updated to make the optional semantics explicit rather than keeping fulfils mandatory:

  • tool_req__docs_arch_link_fulfils reworded and bumped to version 3 (title "Architecture fulfils linkage rules"; text now: "allow or enforce where necessary that linking via the fulfils attribute follows the defined rules"), allowed-combinations table retained.
  • tool_req__docs_arch_link_fulfils_aou bumped to version 3 and reworded to permit (not require) a fulfils link to aou_req. This aligns with the base process requirement gd_req__arch_attr_fulfils, which is optional in the process repo.
  • Added tests: an unlinked static view is accepted, and an invalid fulfils target is still rejected (feat_arc_sta__fulfils__optional / feat_arc_sta__fulfils__bad_target in test_options_options.rst).

Addressed in c07e9cf.

tags:
- architecture_element
- architecture_view
Expand All @@ -453,9 +454,11 @@ needs_types:
# req-Id: tool_req__docs_common_attr_status
status: ^(valid|invalid)$
mandatory_links:
fulfils: feat_req
# req-Id: tool_req__docs_arch_links
belongs_to: feat
optional_links:
# req-Id: tool_req__docs_arch_link_fulfils
fulfils: feat_req
tags:
- architecture_view
- architecture_element
Expand Down Expand Up @@ -561,14 +564,15 @@ needs_types:
safety: ^(QM|ASIL_B)$
# req-Id: tool_req__docs_common_attr_status
status: ^(valid|invalid)$

mandatory_links:
belongs_to: feat # preparation for linking change according to DR-005
optional_links:
# req-Id: tool_req__arch_linkage_safety
implements: logic_arc_int, real_arc_int_op
uses: logic_arc_int, real_arc_int_op
consists_of: comp
# tool_req__docs_arch_link_fulfils_aou
fulfils: aou_req
tags:
- architecture_element
parts: 2
Expand All @@ -589,10 +593,10 @@ needs_types:
mandatory_links:
# req-Id: tool_req__docs_arch_links
belongs_to: comp
# req-Id: tool_req__docs_arch_link_fulfils, tool_req__docs_arch_link_fulfils_aou
fulfils: comp_req, aou_req
optional_links:
uses: logic_arc_int, real_arc_int_op
# req-Id: tool_req__docs_arch_link_fulfils, tool_req__docs_arch_link_fulfils_aou
fulfils: comp_req
tags:
- architecture_view
parts: 3
Expand All @@ -613,6 +617,7 @@ needs_types:
mandatory_links:
# req-Id: tool_req__docs_arch_links
belongs_to: comp
optional_links:
fulfils: comp_req
tags:
- architecture_view
Expand Down
25 changes: 25 additions & 0 deletions src/extensions/score_metamodel/tests/rst/options/test_options_options.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -223,6 +223,31 @@
--- feat_saf_fmea violates end ---


--- arch fulfils optional begin ---

.. Positive Test: fulfils is optional for static views, an unlinked feat_arc_sta is accepted.
.. feat_arc_sta:: Static view without fulfils
:id: feat_arc_sta__fulfils__optional
:status: valid
:safety: ASIL_B
:security: YES
:expect_not: is missing required link: `fulfils`


.. Negative Test: when fulfils is present, its target type is still restricted.
.. feat_arc_sta:: Static view with invalid fulfils target
:id: feat_arc_sta__fulfils__bad_target
:status: valid
:safety: ASIL_B
:security: YES
:fulfils: comp_req__child__ASIL_B
:expect: feat_arc_sta__fulfils__bad_target: references 'comp_req__child__ASIL_B' as 'fulfils', but it must reference Feature Requirement (feat_req) or Assumption of Use Requirement (aou_req).

--- arch fulfils optional end ---


.. Tests if the attribute `safety` follows the pattern `^(QM|ASIL_B)$`
.. document:: This is a test document
Expand Down
Loading