Traceability is the cornerstone of any formal documentation system, especially those intended for managing functional safety. It enables product teams to associate every work artifact (e.g., a specific requirement) with all the related project artifacts (e.g., design, code, or tests), both backward and forward. Traceability enables everyone to see how every work artifact relates to the requirement — and vice versa — at any point during development. This ability fosters team collaboration and enables early detection of possible production risks.

Attention: spexygen provides consistent and automated management of traceability within the whole documentation set.

Unique Identifiers (UIDs)

Traceability is enabled by the consistent use of Unique Identifiers (UIDs), which are short text labels associated with all work artifacts, such as requirements, architecture elements, design elements, coding standard deviations, tests, functional safety documents, etc.

Note: The structure of UIDs is flexible to accommodate various existing naming conventions. But for compatibility with the widest possible range of cross-referencing systems and tools, the UIDs are restricted to generally follow the rules for identifiers in programming languages, such as identifiers in C, C++, or Python. Specifically, valid UIDs can contain only upper-case letters (A..Z), numbers (0..9), and underscores ('_'). Among others, UIDs cannot contain spaces, punctuation, parentheses, or any special characters like !, @, #, $, etc.

Remarks: Restricting the UIDs to the programming language identifiers allows you to use the UIDs as identifiers. For example, you might name test functions as their UIDs. Additionally, such UIDs become searchable with the doxygen built-in search (the "Search Box").

The most important feature of UIDs is their uniqueness within the whole system under consideration. To avoid name conflicts, it is advantageous to establish general rules for constructing the UIDs. Throughout spexygen documentation, the UIDs have the general structure consisting of fields separated by underscores:

 +------------------ [1] Work artifact type (e.g., 'SRS' for Software Requirement Specification)
 |   +-------------- [2] Component unique identifier (e.g, 'QP' for QP Framework)
 |   |   +---------- [3] Work artifact ID (abbreviation or number)
 |   |   |  +------- [4] Work artifact number
 |   |   |  |   +--- [5] Optional variant letter ('A', 'B', 'C'...)
 |   |   |  |   |+-- [6] Optional version number (1, 2, 3...)
 |   |   |  |   ||
SRS_xxx_yyy_zz[_A2]

Examples: SRS_QP_AO_10, SAS_QP_QHsm

The various fields in the UID are as follows:

UID Type

[1] the UID starts with a fields corresponding to the type of the work artifact. Here are the suggested artifact type names:

DOC Document
SRS Software Requirement Specification
SSR Software Safety Requirement
SAS Software Architecture Specification
SDS Software Design Specification
FSM Functional Safety Management artifact
SHR Software Hazard and Risk artifact
DVR Deviation Record (e.g. coding standard violation)
DVP Deviation Permit (e.g. coding standard violation)
TUN Test (unit)
TIN Test (integration)
TAC Test (acceptance)

Attention: The type filed of the UID should be carefully chosen to allow filtering and cross-referencing artifacts of various types. For example, requirements traceability matrix (often needed for compliance with functional safety standards) is a relationship between the requirements (type SRS) and various other work items (e.g., tests, TUN, TIN, or TAC).

UID Component

[2] the Component Unique Identifier (CUI) denotes the component addressed by this UID, which should be unique enough to avoid name conflicts with other software components in a larger system.

UID Subject

[3] "Work artifact ID" field identifies the artifact subject within the "work artifact type" [1]. This is the most flexible part in the UID to accommodate other existing conventions, such as MISRA deviations, the work artifact ID field should be easily identifiable with the MISRA Rule/Directive ID, such as D04_01 for "Directive 4.1", or R10_04 for "Rule 10.4". Still, please note that the more structured UID convention of using two-digits for feature groups (e.g., D04_10 instead of D4_10) provide additional benefits, such as correct order under a simple alphabetical sort. This property is missing in the original MISRA IDs (e.g., a simple alphabetical sort will place Rule 10.8 before Rule 8.10).

UID Number

[4] "Work artifact number" filed identifies the aspect of the work artifact

UID Variant

[5] optionally, the UID might contain a variant letter ('A', 'B', 'C',...)

UID Version

[6] optionally, the UID might end with a single-digit version number (0..9).

Alternatively, UIDs of code elements follow the rules established by doxygen, with the following general form:

     +-------------- [1] Namespace (e.g., module, class)
     |          +--- [2] element (e.g., attribute or operation)
     |          |
[namespace]_[element]

Examples: QHsm::QHsm_ctor(), QTimeEvt::QTimeEvt_disarm()

Backward Traceability

Backward traceability begins at a specific work artifact and links it to the original artifact. For example, architecture element can be linked with an upstream requirement, or code artifact with the upstream design. Backward traceability gives visibility into why specific artifacts were created and how different pieces of a system fit together. Tracing in this way also allows testers to find gaps or missing work artifacts.

Remarks: Backward traceability is the most natural and efficient way of specifying hierarchical relationships, such as superclass-subclass in object-oriented programming (OOP). Class inheritance is universally represented in the subclasses, which store their superclass (backward traceability). In contrast, superclasses don't show their subclasses (forward traceability). This functional safety management system applies this approach to all work artifacts, starting with the requirements at the top, through architecture, design, source code, tests, deviations, etc.

As illustrated in the diagram below, backward traceability is provided explicitly in the spexygen documentation and the source code. Specifically, the downstream work artifacts provide trace information to the related upstream artifact by means of the Unique Identifier (UIDs).

Schematic View of Backward Traceability in the spexygen documentation

Note: The spexygen documentation traceability system includes the source code. This is achieved by placing special backward traceability links, such as @ref SRS_PRJ_Foo_03 "SRS_PRJ_Foo_03" or @ref free_fun() "free_fun()", inside the spexygen documentation for the source code.

Forward Traceability

Forward traceability begins at the original artifact and links it with all the resulting forward work items. For example, a requirement can be linked with source code elements that implement that requirement. This type of trace ensures that each original artifact (e.g., requirement) is not only satisfied but verified and validated. In the spexygen documentation the forward traceability is generated automatically by the spexygen.py Python script.

Note: Forward traceability is typically recursive meaning that if artifact A traces to B and B traces to C, then artifact A also traces to C. Spexygen generates recursive forward trace, which enables the teams to perform impact analysis to identify the potential consequences of a change of a given artifact.

Bidirectional Traceability

Bidirectional traceability is the ability to perform both forward and backward traceability. Bidirectional traceability is the optimal type of traceability because it gives teams full visibility from requirements through architecture, design, source code, tests, and back again. The system implemented in the spexygen documentation provides such bidirectional traceability.

Remarks: The whole system of traceability offered in spexygen is extensible and can be used in any technical documentation system.

Purpose and Scope