diff options
Diffstat (limited to 'eng/req/traceability.rst')
| -rw-r--r-- | eng/req/traceability.rst | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/eng/req/traceability.rst b/eng/req/traceability.rst new file mode 100644 index 0000000..99c4931 --- /dev/null +++ b/eng/req/traceability.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019, 2020 embedded brains GmbH & Co. KG + +.. _ReqEngTrace: + +Traceability of Specification Items +=================================== + +The standard ECSS-E-ST-10-06C demands that requirements shall be under +configuration management, backwards-traceable and forward-traceable +:cite:`ECSS_E_ST_10_06C`. Requirements are a specialization of specification +items in RTEMS. + +.. _ReqEngTraceHistory: + +History of Specification Items +------------------------------ + +The RTEMS specification items should placed in the RTEMS sources using Git for +version control. The history of specification items can be traced with Git. +Special commit procedures for changes in specification item files should be +established. For example, it should be allowed to change only one +specification item per commit. A dedicated Git commit message format may be +used as well, e.g. use of ``Approved-by:`` or ``Reviewed-by:`` lines which +indicate an agreed statement (similar to the +`Linux kernel patch submission guidelines <https://www.kernel.org/doc/html/latest//process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes>`_). +Git commit procedures may be ensured through a server-side pre-receive hook. +The history of requirements may be also added to the specification items +directly in a *revision* attribute. This would make it possible to generate +the history information for documents without having the Git repository +available, e.g. from an RTEMS source release archive. + +.. _ReqEngTraceBackward: + +Backward Traceability of Specification Items +-------------------------------------------- + +Providing backward traceability of specification items means that we must be +able to find the corresponding higher level specification item for each refined +specification item. A custom tool needs to verify this. + +.. _ReqEngTraceForward: + +Forward Traceability of Specification Items +------------------------------------------- + +Providing forward traceability of specification items means that we must be +able to find all the refined specification items for each higher level +specification item. A custom tool needs to verify this. The links from +parent to child specification items are implicitly defined by links from a +child item to a parent item. + +.. _ReqEngTraceReqArchDesign: + +Traceability between Software Requirements, Architecture and Design +------------------------------------------------------------------- + +The software requirements are implemented in custom YAML files, see +:ref:`ReqEngSpecificationItems`. The software architecture and design is +written in Doxygen markup. Doxygen markup is used throughout all header and +source files. A Doxygen filter program may be provided to place Doxygen markup +in assembler files. The software architecture is documented via Doxygen +groups. Each Doxygen group name should have a project-specific name and the +name should be unique within the project, e.g. RTEMSTopLevel\ MidLevel\ +LowLevel. The link from a Doxygen group to its parent group is realized +through the ``@ingroup`` special command. The link from a Doxygen group or +:term:`software component` to the corresponding requirement is realized through +a ``@satisfy{req}`` `custom command +<http://www.doxygen.nl/manual/custcmd.html>`_ which needs the identifier of the +requirement as its one and only parameter. Only links to parents are +explicitly given in the Doxygen markup. The links from a parent to its +children are only implicitly specified via the link from a child to its parent. +So, a tool must process all files to get the complete hierarchy of software +requirements, architecture and design. Links from a software component to +another software component are realized through automatic Doxygen references or +the ``@ref`` and ``@see`` special commands. |