1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
.. SPDX-License-Identifier: CC-BY-SA-4.0
.. Copyright (C) 2019, 2020 embedded brains GmbH (http://www.embedded-brains.de)
Tooling
=======
Tool Requirements
-----------------
To manage requirements some tool support is helpful. Here is a list of
requirements for the tool:
* The tool shall be open source.
* The tool should be actively maintained during the initial phase of the RTEMS
requirements specification.
* The tool shall use plain text storage (no binary formats, no database).
* The tool shall support version control via Git.
* The tool should export the requirements in a human readable form using the
Sphinx documentation framework.
* The tool shall support traceability of requirements to items external to the
tool.
* The tool shall support traceability between requirements.
* The tool shall support custom requirement attributes.
* The tool should ensure that there are no cyclic dependencies between
requirements.
* The tool should provide an export to :term:`ReqIF`.
Tool Evaluation
---------------
During an evaluation phase the following tools were considered:
* `aNimble <https://sourceforge.net/projects/nimble/>`_
* :term:`Doorstop`
* `OSRMT <https://github.com/osrmt/osrmt>`_
* `Papyrus <https://www.eclipse.org/papyrus/>`_
* `ProR <https://www.eclipse.org/rmf/pror/>`_
* `ReqIF Studio <https://formalmind.com/tools/studio/>`_
* `Requirement Heap <https://sourceforge.net/projects/reqheap/>`_
* `rmToo <http://rmtoo.florath.net/>`_
The tools aNimble, OSRMT and Requirement Heap were not selected since they use
a database. The tools Papyrus, ProR and ReqIF are Eclipse based and use
complex XML files for data storage. They were difficult to use and lack good
documentation/tutorials. The tools rmToo and Doorstop turned out to be the
best candidates to manage requirements in the RTEMS Project. The Doorstop tool
was selected as the first candidate mainly due a recommendation by an RTEMS
user.
.. _ReqEngDoorstop:
Best Available Tool - Doorstop
------------------------------
:term:`Doorstop` is a requirements management tool. It has a modern,
object-oriented and well-structured implementation in Python 3.6 under the
LGPLv3 license. It uses a continuous integration build with style checkers,
static analysis, documentation checks, code coverage, unit test and integration
tests. In 2019, the project was actively maintained. Pull requests for minor
improvements and new features were reviewed and integrated within days. Each
requirement is contained in a single file in :term:`YAML` format. Requirements
are organized in documents and can be linked to each other
:cite:`Browning:2014:RequirementsManagement`.
Doorstop consists of three main parts
* a stateless command line tool `doorstop`,
* a file format with a pre-defined set of attributes (YAML), and
* a primitive GUI tool (not intended to be used).
For RTEMS, its scope could be extended to manage specifications in general.
The primary reason for a close consideration of Doorstop as the requirements
management tool for the RTEMS Project was its data format which allows a high
degree of customization. Doorstop uses a directed, acyclic graph (DAG) of
items. The items are files in YAML format. Each item has a set of
`standard attributes <https://doorstop.readthedocs.io/en/latest/reference/item/>`_
(key-value pairs).
The use case for the standard attributes is requirements management. However,
Doorstop is capable to manage custom attributes as well. We will heavily use
custom attributes for the specification items. Enabling Doorstop to effectively
use custom attributes was done specifically for the RTEMS Project in several
patch sets which in the end turned out to be not enough to use Doorstop for the
RTEMS Project.
A key feature of Doorstop is the `fingerprint of items
<https://doorstop.readthedocs.io/en/latest/reference/item/#reviewed>`_.
For the RTEMS Project, the fingerprint hash algorithm was changed from MD5 to
SHA256. In 2019, it can be considered cryptographically secure. The
fingerprint should cover the normative values of an item, e.g. comments etc. are
not included. The fingerprint would help RTEMS users to track the significant
changes in the requirements (in contrast to all the changes visible in Git).
As an example use case, a user may want to assign a project-specific status to
specification items. This can be done with a table which contains columns for
1. the UID of the item,
2. the fingerprint, and
3. the project-specific status.
Given the source code of RTEMS (which includes the specification items) and this
table, it can be determined which items are unchanged and which have another
status (e.g. unknown, changed, etc.).
After some initial work with Doorstop some issues surfaced
(`#471 <https://github.com/doorstop-dev/doorstop/issues/471>`_).
It turned out that Doorstop is not designed as a library and contains too much
policy. This results in a lack of flexibility required for the RTEMS Project.
1. Its primary use case is requirements management. So, it has some standard
attributes useful in this domain, like derived, header, level, normative,
ref, reviewed, and text. However, we want to use it more generally for
specification items and these attributes make not always sense. Having them
in every item is just overhead and may cause confusion.
2. The links cannot have custom attributes, e.g. role, enabled-by. With
link-specific attributes you could have multiple DAGs formed up by the same
set of items.
3. Inside a document (directory) items are supposed to have a common type (set
of attributes). We would like to store at a hierarchy level also distinct
specializations.
4. The verification of the items is quite limited. We need verification with
type-based rules.
5. The UIDs in combination with the document hierarchy lead to duplication,
e.g. a/b/c/a-b-c-d.yml. You have the path (a/b/c) also in the file name
(a-b-c). You cannot have relative UIDs in links (e.g. ../parent-req) . The
specification items may contain multiple requirements, e.g. min/max
attributes. There is no way to identify them.
6. The links are ordered by Doorstop alphabetically by UID. For some
applications, it would be better to use the order specified by the user. For
example, we want to use specification items for a new build system. Here it
is handy if you can express things like this: A is composed of B and C.
Build B before C.
.. _ReqEngManagementTool:
Custom Requirements Management Tool
-----------------------------------
No requirements management tool was available that fits the need of the RTEMS
Qualification Project. The decision was to develop a custom requirements
management tool written in Python 3.6 or later. The design for it is heavily
inspired by Doorstop.
|
