[rtems-docs commit] eng: Update requirements tooling section

[Sebastian Huber]

Module:    rtems-docs
Branch:    master
Commit:    459326c2b9a829852782170deed0e5876c1258f5
Changeset: http://git.rtems.org/rtems-docs/commit/?id=459326c2b9a829852782170deed0e5876c1258f5

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Fri May 29 08:57:57 2020 +0200

eng: Update requirements tooling section

Update #3715.

---

 eng/req/tooling.rst | 33 ++++++++++++++++++++++-----------
 1 file changed, 22 insertions(+), 11 deletions(-)

diff --git a/eng/req/tooling.rst b/eng/req/tooling.rst
index 9c175fc..3ca166b 100644
--- a/eng/req/tooling.rst
+++ b/eng/req/tooling.rst
@@ -80,11 +80,11 @@ Doorstop consists of three main parts
 
 * 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
+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).
 
@@ -92,16 +92,17 @@ 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.
+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 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
+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,
@@ -115,8 +116,8 @@ 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
+(`#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
@@ -147,3 +148,13 @@ policy. This results in a lack of flexibility required for the RTEMS Project.
    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.