[PATCH] eng: Update requirements tooling section

[Gedare Bloom]

On Fri, May 29, 2020 at 1:19 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> 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..28461e9 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
> +-----------------------------------
> +
> +Since no requirements management tool was available that fits the need of the
Delete "Since"

> +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.
> --
> 2.26.2
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel