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
|
||||
Enforce that Need IDs follow the following naming scheme:
|
|||||
π·οΈ Title#
Enforces title wording rules
|
status: valid
security: NO
safety: ASIL_B
|
||||
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
|
||||
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 Current implementation is handled mainly by sphinx-needs. In our enviroment it supports whole numbers e.g. (1,2,10,34) |
|||||
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
|
||||
Enforce that each Generic 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
|
|||||
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: valid
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:
|
|||||||||||||||
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 |
|||||
Requirement linkage to AoU via covers
|
status: valid
security: NO
safety: ASIL_B
|
||||
Feature requirements (feat_req) and component requirements (comp_req)
link to Assumptions of Use (aou_req) via the |
|||||
ποΈ Architecture#
π’ Architecture Types#
Architecture Types
|
status: valid
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:
|
|||||||||||||||||||
Architecture fulfils linkage to AoU
|
status: valid
security: NO
safety: ASIL_B
|
||||
Architectural static views (feat_arc_sta, comp_arc_sta)
link to Assumptions of Use (aou_req) via the |
|||||
Check Architecture linkage to AoU
|
status: valid
security: NO
safety: ASIL_B
|
||||
Architectural static views (feat_arc_sta, comp_arc_sta)
are not linked to their own AoU via the |
|||||
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 requirement sphinx-needs objects. 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 |
|||||
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: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall ensure that test cases link to requirements on the correct level:
|
|||||
Provide Metrics for linked requirements
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-AS-Code shall provide a way to gather statistics on linkages to implementation(source_code_links) & tests(testlink) for all needs. It shall also be possible to filter these by type and use the provided statistics in the documentation (via diagrams drawn from it etc.) |
|||||
π§ͺ 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 tool_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:
|
|||||
Workproduct Types
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall support the following workproduct types:
|
|||||
Standard Requirement Types
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall support the following requirement types:
|
|||||
Standard Workproduct 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
|
||||
Docs-As-Code shall support the following need types:
|
|||||
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.
|
|||||||||||||||
FMEA: fault id attribute
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-As-Code shall enforce that needs of type FMEA (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 failure_id attribute. Note: Allowed values are listed as ID in tables at gd_guidl__dfa_failure_initiators. This is not verified. |
|||||
Failure Effect
|
status: valid
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) |
|||||
Safety Analysis (DFA + FMEA) Process to Tool Requirement Mapping#
Safety Analysis Safety Relevant 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) and
|
|||||
FMEA: Root Cause Attribute
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-As-Code shall allow FMEA needs ( |
|||||
π Security Analysis#
Security Analysis Need Types
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-As-Code shall support the following need types:
|
|||||
Security Analysis: STRIDE Threat ID Attribute
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-As-Code shall enforce that STRIDE threat needs
( |
|||||
Security Analysis Threat Scenario Mandatory Attributes
|
status: valid
security: NO
safety: ASIL_B
|
||||
Enforce that threat scenario needs
(
|
|||||
Security Analysis Optional Attributes
|
status: valid
security: NO
safety: ASIL_B
|
||||
Allow threat scenario needs
(
|
|||||
πΊοΈ Full Mapping#
Process to tools: