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.
ποΈ 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
|
||||
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
|
||||
Docs-as-Code shall enforce that Need IDs follow the following naming scheme:
|
|||||
π·οΈ Title#
Enforces title wording rules
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall enforce that all needs have titles and titles do not contain the following words:
|
|||||
π Description#
Enforces presence of description
|
status: valid
security: NO
safety: ASIL_B
|
||||
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
|
||||
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
This rule applies to:
|
|||||
π‘οΈ Safety Classification#
Safety: enforce classification
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall enforce that the
This rule applies to:
|
|||||
π¦ Status#
Status: enforce attribute
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall enforce that the
This rule applies to:
|
|||||
Versioning#
Versioning: enforce attribute
|
status: valid
security: NO
safety: ASIL_B
|
||||
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
|
||||
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
|
||||
Docs-as-Code shall support the following document types:
|
|||||
Mandatory attributes of Generic Documents
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall enforce that each Generic Document
|
|||||
Mandatory Document attributes
|
status: invalid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall enforce that each Document Types (tool_req__docs_doc_types) has the following attributes:
|
|||||
Document author is autofilled
|
status: invalid
security: NO
safety: ASIL_B
|
||||
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
|
||||
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
|
||||
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:
|
|||||
π·οΈ Attributes#
Enforces rationale attribute
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall enforce that each stakeholder requirement (stkh_req) contains a |
|||||
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
|
|||||
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.
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
Note No concept yet |
|||||
Enforce validity attribute correctness
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall enforce that the 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
|
||||
Docs-as-Code shall enforce that |
|||||
π Links#
Enables needs linking via satisfies attribute
|
status: invalid
security: NO
safety: ASIL_B
|
||||||||||||||
Docs-as-Code shall enforce that linking between model elements via the Allowed source and target combinations are defined in the following table:
Note Certain tool requirements do not have a matching process requirement. |
|||||||||||||||
Safety: enforce safe linking
|
status: valid
security: NO
safety: ASIL_B
|
||||
QM requirements (safety == QM) shall not be linked to safety requirements (safety != QM) via the |
|||||
ποΈ Architecture#
π’ Architecture Types#
Architecture Types
|
status: invalid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall support the following architecture element types:
|
|||||
Architecture Attributes#
Architecture Mandatory Attributes
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall enforce that the following attributes are present in all needs of type Architecture Types (tool_req__docs_arch_types)
|
|||||
π Linkage#
Mandatory Architecture Attribute: fulfils
|
status: valid
security: NO
safety: ASIL_B
|
||||||||||||||||||
Docs-as-Code shall enforce that linking via the Allowed source and target combinations are defined in the following table:
|
|||||||||||||||||||
Ensure safety architecture elements link a safety requirement
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall enforce that architecture elements of type
Architecture Types (tool_req__docs_arch_types) with |
|||||
Ensure qm architecture elements do not fulfill safety requirements
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall enforce that architecture elements of type
Architecture Types (tool_req__docs_arch_types) with |
|||||
Restrict links for safety requirements
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall enforce that valid safety architectural elements (Safety != QM) can only be linked against valid safety architectural elements. |
|||||
Security: Restrict linkage
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall enforce that security relevant Architecture Types (tool_req__docs_arch_types) (Security == YES) can only be linked against security relevant Architecture Types (tool_req__docs_arch_types). |
|||||
π» Detailed Design & Code#
π Code Linkage#
Supports linking to source code
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall allow source code to link to needs. A link to the corresponding source code location in GitHub shall be generated in the generated documentation within the linked requirement. |
|||||
Feature Flags
|
status: valid
security: NO
safety: ASIL_B
|
||||
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
|
||||
Provide needs type |
|||||
Dynamic Diagram for Unit Interactions
|
status: valid
security: NO
safety: ASIL_B
|
||||
Provide needs type |
|||||
Testing#
Supports linking to test cases
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall allow requirements of type Requirements Types (tool_req__docs_req_types) to
include a This attribute shall support linking test cases to requirements. |
|||||
Extract Metadata from Tests
|
status: valid
security: NO
safety: ASIL_B
|
||||
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
|
||||
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. |
|||||
Extract Metadata from Tests
|
status: invalid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall ensure that test cases link to requirements on the correct level:
|
|||||
π§ͺ Tool Verification Reports#
Enforce safety classification
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall enforce that every Tool Verification Report (doc_tool) includes a
|
|||||
Enforce security classification
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall enforce that every Tool Verification Report (doc_tool) includes a security_affected attribute with one of the following values:
|
|||||
Enforce status classification
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall enforce that every Tool Verification Report (doc_tool) includes a status attribute with one of the following values:
|
|||||
Enforce version attribute
|
status: valid
security: NO
safety: ASIL_B
|
||||
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
|
||||
Docs-as-Code shall enforce that every Tool Verification Report (doc_tool) includes a tcl attribute with one of the following values:
|
|||||
βοΈ Process / Other#
Workflow Types
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall support the following workflow types:
|
|||||
Standard Requirement Types
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall support the following requirement types:
|
|||||
π‘οΈ Safety Analysis (DFA + FMEA)#
Safety Analysis Need Types
|
status: valid
security: NO
safety: ASIL_B
|
||||
|
|||||
Safety Analysis Mandatory Attributes
|
status: valid
security: NO
safety: ASIL_B
|
||||
All safety analysis elements in Safety Analysis Need Types (tool_req__docs_saf_types) shall have the following mandatory attributes:
|
|||||
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 |
|||||
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:
|
|||||
Safety Analysis Sufficient Check
|
status: valid
security: NO
safety: ASIL_B
|
||||
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
|
||||
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
|
||||
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
|
||||
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:
Overview of Tool to Process Requirements#
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β. |
|||||