Tool Requirements#

πŸ“ˆ Status#

This section provides an overview of current process requirements and their clarification & implementation status.

Note

All open issues and pull requests in the process repository are considered as if they are already part of the process requirements. They address a lot of the requirements that are referenced in this document, so we would be blocked if we would not consider them as part of the process requirements.

Docs-As-Code Requirements Status

πŸ—‚οΈ Common Attributes#

Note

To stay consistent with sphinx-needs (the tool behind docs-as-code), we’ll use need for any kind of model element like a requirement, an architecture element or a feature description.

πŸ”’ ID#

Enforces need ID uniqueness
status: valid
security: NO
safety: ASIL_B
tags: Common Attributes
implemented: YES
parent_covered: NO

Docs-as-Code shall enforce that all Need IDs are globally unique across all included documentation instances.

Note

Within each docs-instance (as managed by sphinx-needs), IDs are guaranteed to be unique. When linking across instances, unique prefixes are automatically applied to maintain global uniqueness.

Enforces need ID scheme
status: valid
security: NO
safety: ASIL_B
tags: Common Attributes
implemented: PARTIAL
parent_covered: NO: cannot check non-existent "doc__naming_conventions" in gd_req__req_attr_uid

Docs-as-Code shall enforce that Need IDs follow the following naming scheme:

  • A prefix indicating the need type (e.g. feature__)

  • A middle part matching the hierarchical structure of the need:
    • For requirements: a portion of the feature tree or a component acronym

    • For architecture elements: the structural element (e.g. a part of the feature tree, component acronym)

    • For safety analysis (FMEA, DFA): name of analyzed structural element (e.g. Persistency, FEO, etc.)

  • Additional descriptive text to ensure human readability

🏷️ Title#

Enforces title wording rules
status: valid
security: NO
safety: ASIL_B
tags: Common Attributes, config
implemented: YES
parent_covered: NO: Can not ensure summary

Docs-as-Code shall enforce that all needs have titles and titles do not contain the following words:

  • shall

  • must

  • will

πŸ“ Description#

Enforces presence of description
status: valid
security: NO
safety: ASIL_B
tags: Common Attributes
implemented: YES
parent_covered: NO: Can not cover 'ISO/IEC/IEEE/29148'

Docs-as-Code shall enforce that each need of type Requirements Types (tool_req__docs_req_types) has a description (content)

Enforces description wording rules
status: valid
security: NO
safety: ASIL_B
tags: Common Attributes, config
implemented: YES
parent_covered: YES

Docs-as-Code shall enforce that requirement descriptions do not contain the following weak words: ju-st, ab-out, rea-lly, so-me, th-ing, absol-utely

This rule applies to:

Note

Artificial β€œ-” added to avoid triggering violation of this requirment in this document.

πŸ”’ Security Classification#

Security: enforce classification
status: valid
security: NO
safety: ASIL_B

Docs-as-Code shall enforce that the security attribute has one of the following values:

  • YES

  • NO

This rule applies to:

πŸ›‘οΈ Safety Classification#

Safety: enforce classification
status: valid
security: NO
safety: ASIL_B

Docs-as-Code shall enforce that the safety attribute has one of the following values:

  • QM

  • ASIL_B

This rule applies to:

🚦 Status#

Status: enforce attribute
status: valid
security: NO
safety: ASIL_B

Docs-as-Code shall enforce that the status attribute has one of the following values:

  • valid

  • invalid

This rule applies to:

Versioning#

Versioning: enforce attribute
status: valid
security: NO
safety: ASIL_B
tags: Common Attributes
implemented: NO
parent_covered: NO: to be checked after demo

Docs-As-Code shall enable and enforce a versioning attribute for all needs.

Note

Exact nature to be decided, it could e.g. be a number, a string, a semantic version, a date or a hash.

Suspicious: Enforce attribute
status: invalid
security: NO
safety: ASIL_B
tags: Common Attributes
implemented: NO
parent_covered: NO: parent talks about setting covered to false, but we want to issue a build error.

Docs-as-Code shall check if linked parent needs have different versions, compared to the version the need was originally linked to.

πŸ“š Documents#

Document Types
status: valid
security: NO
safety: ASIL_B
tags: Documents, config
implemented: YES
parent_covered: YES

Docs-as-Code shall support the following document types:

  • Generic Document (document)

  • Tool Verification Report (doc_tool)

  • Change Request is also a generic document

Mandatory attributes of Generic Documents
status: valid
security: NO
safety: ASIL_B

Docs-as-Code shall enforce that each Generic Document doc__* has the following attributes:

  • status

  • security

  • safety

  • realizes

Mandatory Document attributes
status: invalid
security: NO
safety: ASIL_B
tags: Documents, config
implemented: NO
parent_covered: NO, process requirement has changed and we do not understand the new wording.

Docs-as-Code shall enforce that each Document Types (tool_req__docs_doc_types) has the following attributes:

  • title (implicitly enforced by sphinx-needs)

  • author

  • approver

  • reviewer

Document author is autofilled
status: invalid
security: NO
safety: ASIL_B
tags: Documents
implemented: NO
parent_covered: NO, process requirement has changed and we do not understand the new wording.

Docs-as-Code shall provide an automatic mechanism to determine document authors.

Contributors responsible for more than 50% of the content shall be considered the document author. Contributors are accumulated over all commits to the file containing the document.

Note

The requirement is currently invalid as it’s currently unclear how the contribution % are counted and how to accumulate %.

Document approver is autofilled
status: invalid
security: NO
safety: ASIL_B
tags: Documents
implemented: NO
parent_covered: NO, process requirement has changed and we do not understand the new wording.

Docs-as-Code shall provide an automatic mechanism to determine the document approver.

The approver shall be the approvers listed in CODEOWNERS of the last pull request of the file containing the document.

Document reviewer is autofilled
status: invalid
security: NO
safety: ASIL_B
tags: Documents
implemented: NO
parent_covered: NO, process requirement has changed and we do not understand the new wording.

Docs-as-Code shall provide an automatic mechanism to determine the document reviewers.

The reviewer shall be the approvers NOT listed in CODEOWNERS of the last pull request of the file containing the document.

Mapping#

πŸ“‹ Requirements#

πŸ”’ Requirement Types#

Requirements Types
status: valid
security: NO
safety: ASIL_B

Docs-as-Code shall support the following requirement types:

  • Stakeholder requirement (stkh_req)

  • Feature requirement (feat_req)

  • Component requirement (comp_req)

  • Assumption of use requirement (aou_req)

  • Process requirement (gd_req)

  • Tool requirement (tool_req)

🏷️ Attributes#

Enforces rationale attribute
status: valid
security: NO
safety: ASIL_B
tags: Requirements, config
implemented: YES
parent_covered: NO: Can not ensure correct reasoning

Docs-as-Code shall enforce that each stakeholder requirement (stkh_req) contains a rationale attribute.

Enforces requirement type classification
status: valid
security: NO
safety: ASIL_B

Docs-as-Code shall enforce that each need of type Requirements Types (tool_req__docs_req_types) except process and tool requirements has a reqtype attribute with one of the following values:

  • Functional

  • Interface

  • Process

  • Non-Functional

Enables marking requirements as "covered"
status: valid
security: NO
safety: ASIL_B

Docs as code shall shall enable marking requirements as covered by their linked children.

Attribute reqcov must be one of the following values:
  • Yes

  • No

Note

No concept yet, as parents are generally not aware of their children.

Support requirements test coverage
status: invalid
security: NO
safety: ASIL_B

Docs-As-Code shall allow for every need of type Requirements Types (tool_req__docs_req_types) to have a testcovered attribute, which must be one of:

  • Yes

  • No

Note

No concept yet

Enforce validity attribute correctness
status: valid
security: NO
safety: ASIL_B
tags: Requirements, config
implemented: PARTIAL
parent_covered: YES

Docs-as-Code shall enforce that the valid_from and valid_until attributes of stakeholder and feature requirements are correct.

The format of a milestone is something like β€œv0.5” or β€œv1.0.1”. No suffixes like β€œ-SNAPSHOT” or β€œ-beta” are allowed.

Enforce validity start is before end
status: valid
security: NO
safety: ASIL_B
tags: Requirements
implemented: PARTIAL
parent_covered: YES

Docs-as-Code shall enforce that valid_from is before valid_until attribute in stakeholder and feature requirements. We consider β€œfrom” is inclusive but β€œuntil” is exclusive, so from v0.5 until v1.0 means valid for v0.5 but not for v1.0. If either attribute is missing, no check is performed.

πŸ›οΈ Architecture#

πŸ”’ Architecture Types#

Architecture Types
status: invalid
security: NO
safety: ASIL_B

Docs-as-Code shall support the following architecture element types:

  • Feature (feat_arc_sta)

  • Logical Interface (logic_arc_int)

  • Logical Interface Operation (logic_arc_int_op)

  • Component (comp_arc_sta)

  • Interface (real_arc_int)

  • Interface Operation (real_arc_int_op)

Architecture Attributes#

Architecture Mandatory Attributes
status: valid
security: NO
safety: ASIL_B
tags: Architecture
implemented: PARTIAL
parent_covered: YES
parent_has_problem: YES: Metamodel & Process aren't the same. Some definitions are not consistent in Process

Docs-as-Code shall enforce that the following attributes are present in all needs of type Architecture Types (tool_req__docs_arch_types)

  • Fulfils

  • Safety

  • Security

  • Status

  • UID

πŸ”— Linkage#

πŸ’» Detailed Design & Code#

πŸ”— Code Linkage#

Feature Flags
status: valid
security: NO
safety: ASIL_B
tags: Detailed Design & Code
implemented: NO
parent_covered: YES

Docs-as-Code shall allow for a to-be-defined list of checks to be non-fatal for non release builds. These are typically better suited for metrics than for checks.

e.g. gd_req__req_linkage_architecture

Static Diagram for Unit Interactions
status: valid
security: NO
safety: ASIL_B
tags: Detailed Design & Code, config
implemented: YES
parent_covered: YES

Provide needs type dd_sta for static diagrams showing unit interactions as UML.

Dynamic Diagram for Unit Interactions
status: valid
security: NO
safety: ASIL_B
tags: Detailed Design & Code, config
implemented: YES
parent_covered: YES

Provide needs type dd_dyn for dynamic diagrams showing unit interactions as UML.

Testing#

Extract Metadata from Tests
status: valid
security: NO
safety: ASIL_B
tags: Testing
implemented: NO
parent_covered: NO

Docs-as-Code shall ensure that each test case has TestType and DerivationTechnique set.

Extract Metadata from Tests
status: invalid
security: NO
safety: ASIL_B
tags: Testing
implemented: NO
parent_covered: NO

Docs-as-Code shall ensure that each test case has a non empty description.

Note

this will probably be implemented outside of docs-as-code.

πŸ§ͺ Tool Verification Reports#

Enforce safety classification
status: valid
security: NO
safety: ASIL_B
tags: Tool Verification Reports, config
implemented: YES
parent_covered: YES

Docs-as-Code shall enforce that every Tool Verification Report (doc_tool) includes a safety_affected attribute with one of the following values:

  • YES

  • NO

Enforce security classification
status: valid
security: NO
safety: ASIL_B
tags: Tool Verification Reports, config
implemented: YES
parent_covered: YES

Docs-as-Code shall enforce that every Tool Verification Report (doc_tool) includes a security_affected attribute with one of the following values:

  • YES

  • NO

Enforce status classification
status: valid
security: NO
safety: ASIL_B
tags: Tool Verification Reports, config
implemented: YES
parent_covered: YES

Docs-as-Code shall enforce that every Tool Verification Report (doc_tool) includes a status attribute with one of the following values:

  • draft

  • evaluated

  • qualified

  • released

  • rejected

Enforce version attribute
status: valid
security: NO
safety: ASIL_B
tags: Tool Verification Reports, config
implemented: YES
parent_covered: YES

Docs-as-Code shall enforce that every Tool Verification Report (doc_tool) includes a version attribute.

Enforce confidence level classification
status: valid
security: NO
safety: ASIL_B
tags: Tool Verification Reports, config
implemented: YES
parent_covered: YES

Docs-as-Code shall enforce that every Tool Verification Report (doc_tool) includes a tcl attribute with one of the following values:

  • LOW

  • HIGH

βš™οΈ Process / Other#

Workflow Types
status: valid
security: NO
safety: ASIL_B

Docs-as-Code shall support the following workflow types:

  • Workflow (wf)

Standard Requirement Types
status: valid
security: NO
safety: ASIL_B
tags: Process / Other, config
implemented: YES

Docs-as-Code shall support the following requirement types:

  • Standard requirement (std_req)

πŸ›‘οΈ Safety Analysis (DFA + FMEA)#

Safety Analysis Need Types
status: valid
security: NO
safety: ASIL_B

Docs-As-Code shall support the following need types:

  • Feature FMEA (Failure Modes and Effect Analysis) -> feat_saf_fmea

  • Component FMEA (Failure Modes and Effect Analysis) -> comp_saf_fmea

  • Feature DFA (Dependend Failure Analysis) -> feat_saf_dfa

  • Component DFA (Dependent Failure Analysis) -> comp_saf_dfa

Safety Analysis Mandatory Attributes
status: valid
security: NO
safety: ASIL_B
tags: Safety Analysis
implemented: YES
parent_covered: YES

All safety analysis elements in Safety Analysis Need Types (tool_req__docs_saf_types) shall have the following mandatory attributes:

  • DFA-only attribute: failure_id

  • FMEA-only attribute: fault_id

  • attribute: failure_effect

  • attribute: status

  • attribute: sufficient

  • attribute: title (all Needs elements have a title)

  • attribute: id (all Needs elements have an id)

Safety Analysis Mitigation Attribute
status: valid
security: NO
safety: ASIL_B

Docs-As-Code shall enforce valid needs (status == valid) of type Safety Analysis Need Types (tool_req__docs_saf_types) to have at least one mitigated_by link to a requirement on the corresponding level.

At least one of the linked requirements must have the same ASIL level or a higher one.

It can be comp_req or aou_req.

Safety Analysis Mitigation Issue Attribute
status: valid
security: NO
safety: ASIL_B

Docs-As-Code shall allow needs of type Safety Analysis Need Types (tool_req__docs_saf_types) to have a mitigation_issue attribute which links to a GitHub issue.

Safety Analysis Sufficient Attribute
status: valid
security: NO
safety: ASIL_B

Docs-As-Code shall enforce needs of type Safety Analysis Need Types (tool_req__docs_saf_types) to have a sufficient attribute , which can have one of the following values:

  • yes

  • no

Safety Analysis Sufficient Check
status: valid
security: NO
safety: ASIL_B
tags: Safety Analysis
implemented: NO
parent_covered: YES

Docs-As-Code shall ensure needs of type Safety Analysis Need Types (tool_req__docs_saf_types) with sufficient == yes have a mitigated_by entry.

Safety Analysis Mandatory Content
status: valid
security: NO
safety: ASIL_B

Docs-As-Code shall enforce needs of type Safety Analysis Need Types (tool_req__docs_saf_types) to have a non empty content.

Safety Analysis Linkage Violates
status: valid
security: NO
safety: ASIL_B

Docs-As-Code shall enforce that needs of type Safety Analysis Need Types (tool_req__docs_saf_types) have a violates links to at least one dynamic / static diagram according to the table.

Source | Target |
– | – |
feat_saf_dfa | feat_arc_sta |
comp_saf_dfa | comp_arc_sta |
feat_saf_fmea | feat_arc_dyn |
comp_saf_fmea | comp_arc_dyn |
FMEA: fault id attribute
status: valid
security: NO
safety: ASIL_B
tags: Safety Analysis, config
implemented: NO
parent_covered: NO

Docs-As-Code shall enforce that needs of type DFA (see Safety Analysis Need Types (tool_req__docs_saf_types)) have a fault_id attribute.

Allowed values are listed as ID in tables at gd_guidl__dfa_failure_initiators.

DFA: failure id attribute
status: valid
security: NO
safety: ASIL_B
tags: Safety Analysis, config
implemented: NO
parent_covered: NO

Docs-As-Code shall enforce that needs of type DFA (see Safety Analysis Need Types (tool_req__docs_saf_types)) have a fault_id attribute.

Allowed values are listed as ID in tables at gd_guidl__dfa_failure_initiators.

Failure Effect
status: invalid
security: NO
safety: ASIL_B
tags: Safety Analysis
implemented: NO
parent_covered: NO

Docs-As-Code shall enforce that every Safety Analysis has a short description of the failure effect (e.g. failure lead to an unintended actuation of the analysed element)

Mapping#

πŸ—ΊοΈ Full Mapping#

Process to tools:

ID

tool_req

tool_req__docs_arch_link_fulfils; tool_req__docs_arch_attr_mandatory

tool_req__docs_arch_attr_mandatory

tool_req__docs_common_attr_safety

tool_req__docs_common_attr_security

tool_req__docs_common_attr_status

tool_req__docs_common_attr_id; tool_req__docs_common_attr_id_scheme

tool_req__docs_arch_types

tool_req__docs_arch_types

tool_req__docs_arch_link_safety_to_req; tool_req__docs_arch_link_qm_to_safety_req

tool_req__docs_arch_link_fulfils

tool_req__docs_req_arch_link_safety_to_arch

tool_req__docs_arch_link_security

tool_req__docs_arch_link_fulfils

tool_req__docs_arch_views

tool_req__docs_doc_generic_mandatory

tool_req__docs_doc_attr

tool_req__docs_doc_attr_approver_autofill; tool_req__docs_doc_attr

tool_req__docs_doc_generic_mandatory

tool_req__docs_doc_attr_author_autofill; tool_req__docs_doc_attr

tool_req__docs_doc_attr_reviewer_autofill; tool_req__docs_doc_attr

tool_req__docs_doc_types

tool_req__docs_dd_link_source_code_link

tool_req__docs_dd_dyn

tool_req__docs_dd_sta

tool_req__docs_wf_types

tool_req__docs_wf_types

tool_req__docs_common_attr_description

tool_req__docs_dd_link_source_code_link

tool_req__docs_req_attr_rationale

tool_req__docs_req_attr_reqcov

tool_req__docs_common_attr_safety

tool_req__docs_common_attr_security

tool_req__docs_common_attr_status

tool_req__docs_req_attr_testcov

tool_req__docs_test_link_testcase

tool_req__docs_common_attr_title

tool_req__docs_req_attr_reqtype

tool_req__docs_common_attr_id; tool_req__docs_common_attr_id_scheme

tool_req__docs_common_attr_version

tool_req__docs_common_attr_description; tool_req__docs_common_attr_status; tool_req__docs_common_attr_safety; tool_req__docs_req_attr_rationale; tool_req__docs_common_attr_security; tool_req__docs_common_attr_id_scheme

tool_req__docs_common_attr_desc_wording

tool_req__docs_req_link_satisfies_allowed

tool_req__docs_dd_feature_flag

tool_req__docs_arch_link_fulfils

tool_req__docs_common_attr_safety_link_check; tool_req__docs_req_arch_link_safety_to_arch

tool_req__docs_req_types

tool_req__docs_common_attr_suspicious

tool_req__docs_req_link_satisfies_allowed

tool_req__docs_req_attr_validity_correctness; tool_req__docs_req_attr_validity_consistency

tool_req__docs_saf_attrs_content

tool_req__docs_saf_attrs_mitigated_by

tool_req__docs_saf_attr_dfa_failure_id

tool_req__docs_saf_attr_fmea_fault_id

tool_req__docs_saf_attr_fmea_failure_effect

tool_req__docs_saf_attrs_mandatory

tool_req__docs_saf_attrs_mitigated_by

tool_req__docs_saf_attrs_mitigation_issue

tool_req__docs_saf_attrs_mitigated_by

tool_req__docs_saf_attrs_mitigated_by

tool_req__docs_common_attr_status

tool_req__docs_saf_attrs_sufficient_check; tool_req__docs_saf_attrs_sufficient

tool_req__docs_common_attr_title

tool_req__docs_common_attr_id; tool_req__docs_saf_types; tool_req__docs_common_attr_id_scheme

tool_req__docs_saf_attrs_violates

tool_req__docs_saf_attrs_violates

tool_req__docs_saf_attrs_mitigated_by

tool_req__docs_saf_types

tool_req__docs_tvr_safety

tool_req__docs_tvr_security

tool_req__docs_tvr_status

tool_req__docs_tvr_confidence_level

tool_req__docs_common_attr_id

tool_req__docs_tvr_version

tool_req__docs_tvr_status; tool_req__docs_tvr_safety; tool_req__docs_tvr_security

tool_req__docs_test_metadata_mandatory_1; tool_req__docs_test_metadata_mandatory_2; tool_req__docs_test_metadata_link_levels

Overview of Tool to Process Requirements#

Process Requirement

Tool Requirement

Implemented

Source Code Link

tool_req__docs_arch_attr_mandatory

PARTIAL

tool_req__docs_arch_link_fulfils

PARTIAL

tool_req__docs_arch_link_qm_to_safety_req

PARTIAL

tool_req__docs_arch_link_safety_to_req

PARTIAL

tool_req__docs_arch_link_security

YES

tool_req__docs_arch_types

YES

tool_req__docs_arch_views

YES

tool_req__docs_common_attr_desc_wording

YES

tool_req__docs_common_attr_description

YES

tool_req__docs_common_attr_id

YES

tool_req__docs_common_attr_id_scheme

PARTIAL

tool_req__docs_common_attr_safety

YES

tool_req__docs_common_attr_safety_link_check

YES

tool_req__docs_common_attr_security

YES

tool_req__docs_common_attr_status

YES

tool_req__docs_common_attr_suspicious

NO

tool_req__docs_common_attr_title

YES

tool_req__docs_common_attr_version

NO

tool_req__docs_dd_dyn

YES

tool_req__docs_dd_feature_flag

NO

tool_req__docs_dd_link_source_code_link

YES

tool_req__docs_dd_sta

YES

tool_req__docs_doc_attr

NO

tool_req__docs_doc_attr_approver_autofill

NO

tool_req__docs_doc_attr_author_autofill

NO

tool_req__docs_doc_attr_reviewer_autofill

NO

tool_req__docs_doc_generic_mandatory

PARTIAL

tool_req__docs_doc_types

YES

tool_req__docs_req_arch_link_safety_to_arch

PARTIAL

tool_req__docs_req_attr_rationale

YES

tool_req__docs_req_attr_reqcov

PARTIAL

tool_req__docs_req_attr_reqtype

YES

tool_req__docs_req_attr_testcov

PARTIAL

tool_req__docs_req_attr_validity_consistency

PARTIAL

tool_req__docs_req_attr_validity_correctness

PARTIAL

tool_req__docs_req_link_satisfies_allowed

PARTIAL

tool_req__docs_req_types

YES

tool_req__docs_saf_attr_dfa_failure_id

NO

tool_req__docs_saf_attr_fmea_failure_effect

NO

tool_req__docs_saf_attr_fmea_fault_id

NO

tool_req__docs_saf_attrs_content

NO

tool_req__docs_saf_attrs_mandatory

YES

tool_req__docs_saf_attrs_mitigated_by

NO

tool_req__docs_saf_attrs_mitigation_issue

YES

tool_req__docs_saf_attrs_sufficient

YES

tool_req__docs_saf_attrs_sufficient_check

NO

tool_req__docs_saf_attrs_violates

NO

tool_req__docs_saf_types

YES

tool_req__docs_test_link_testcase

PARTIAL

tool_req__docs_test_metadata_link_levels

NO

tool_req__docs_test_metadata_mandatory_1

NO

tool_req__docs_test_metadata_mandatory_2

NO

tool_req__docs_tvr_confidence_level

YES

tool_req__docs_tvr_safety

YES

tool_req__docs_tvr_security

YES

tool_req__docs_tvr_status

YES

tool_req__docs_tvr_version

YES

tool_req__docs_wf_types

YES

Grouped Requirements#

Metamodel
status: valid
security: NO
safety: ASIL_B

Docs-as-Code shall provide a metamodel for definining config in a metamodel.yaml in the source code repository.

Note

β€œsatisfied by” is something like β€œused by” or β€œrequired by”.