1 files changed, 149 insertions, 0 deletions
diff --git a/eng/req/tooling.rst b/eng/req/tooling.rst
new file mode 100644
index 0000000..9c175fc
--- /dev/null
+++ b/eng/req/tooling.rst
@@ -0,0 +1,149 @@
+.. 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 will be extended to manage specifications in general.  The
+primary reason for selecting Doorstop as the requirements management tool for
+the RTEMS Project is 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.
+
+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 helps 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 to 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.