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:
|
|||||
Status: skip checks for invalid needs
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall not report any check findings for needs with Needs with |
|||||
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:
A change request is also a generic document but not a Sphinx-Needs type, so out of scope here. |
|||||
Mandatory attributes of Generic Documents
|
status: valid
security: NO
safety: ASIL_B
|
||||
Enforce that each Generic Document
|
|||||
Mapping#
ID |
tool_req |
|---|---|
π 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 Stakeholder and feature requirements require 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: Note The βhaving at least one link is mandatoryβ clause is not enforced yet for
|
|||||||||||||||
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#
Architecture fulfils linkage rules
|
status: valid
security: NO
safety: ASIL_B
|
|||||||||||||||||||||||||
Docs-as-Code shall allow or enforce where necessary 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) and the component itself (comp)
may 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 Note implemented as info to enable non-breaking transition |
|||||
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. Each may contain multiple comma-separated tags of the following:
|
||||||||||||||||||||||||||||||||
See more verification methods for an overview.
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 use only allowed requirement types for their test level. Platform Integration Tests shall link to at least one stakeholder requirement. For other levels, any set verification links shall use the allowed types for that level. The test level is determined from folder structure.
|
||||||||||||||||||||
The folder structure is described in the platform.
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.) |
|||||
π Verification Evidence#
Support machine-readable module verification reports
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall support a machine-readable module verification report need type. The need type shall:
|
|||||
π§ͺ Tool Verification Reports#
Enforce safety classification
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall derive the Tool Verification Report safety classification from its owned potential tool malfunctions:
|
|||||
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 derive the Tool Confidence Level of a Tool Verification Report from its owned potential tool malfunctions:
|
|||||
βοΈ 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:
|
|||||
Decision Record Type
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall support the Decision Record (dec_rec) need type with the following options:
A Decision Record shall be able to link to other needs via the optional |
|||||
Restrict needextend usage
|
status: valid
security: NO
safety: ASIL_B
|
||||
Docs-as-Code shall only allow a
|
|||||
π‘οΈ 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 Note implemented as info to enable non-breaking transition |
|||||
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: