Requirement Identifiers

[Sebastian Huber]

Hello,

I work currently on a requirements engineering section for RTEMS in the 
RTEMS Software Engineering manual:

https://docs.rtems.org/branches/master/eng/index.html

The goal is to add a technical specification for a subset of RTEMS. A 
technical specification consists of requirements. One basic element is 
that requirements can be identified. We have to discuss how requirements 
are identified in the RTEMS project.

The proposed tool to manage requirements in RTEMS is Doorstop:

https://github.com/jacebrowning/doorstop

This tool add some restrictions to the way requirements are identified.

The following text is a part of my requirements engineering draft 
document in ReST format.

Identification
--------------

Each requirement shall have a unique identifier (UID).  The open 
question is in
which scope should it be unique?  Ideally, it should be universally 
unique. As
a best effort approach, the name *RTEMS* shall be used as a part in all
requirement identifiers. This should ensure that the RTEMS requirements 
can be
referenced easily in larger systems.  The standard ECSS-E-ST-10-06C 
recommends
in section 8.2.6 that the identifier should reflect the type of the 
requirement
and the life profile situation.  Other standards may have other
recommendations.  To avoid a bias of RTEMS in the direction of ECSS, this
recommendation will not be followed.  In addition, it would also make 
the use
of :term:`Doorstop` more difficult, since this tool does not support 
attribute
dependent identifiers.

.. topic:: Doorstop

     The UID of an item (requirement) is defined by its file name 
without the
     extension. An UID consists of two parts, the prefix and a number. 
The parts
     are divided by an optional separator. The prefix is determined by the
     document to which the item belongs.

Proposal: Default Doorstop Numbering
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

One UID scheme for RTEMS requirements is the concatenation of *RTEMS* and a
5-digit number which is automatically generated by Doorstop.  It starts with
RTEMS00001 and ends with RTEMS99999.  These identifiers are just unique and
bear no other information.

Proposal: Number Groups
~~~~~~~~~~~~~~~~~~~~~~~

Another UID scheme for RTEMS requirements is the concatenation of 
*RTEMS* and a
5-digit number which reflects the hierarchy of requirements.  For 
example UIDs
from RTEMS01000 to RTEMS01999 are task requirements, UIDs from RTEMS02000 to
RTEMS02999 are semaphore requirements, UIDs from RTEMS03000 to 
RTEMS03999 are
message queue requirements, etc.  It would be also possible to add a 
separator
character, for example RTEMS-01234.

.. topic:: Doorstop

     This is currently not supported by Doorstop, see `issue #349
     <https://github.com/jacebrowning/doorstop/issues/349>`_.

Proposal: Document Hierarchy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Another UID scheme for RTEMS requirements is the concatenation of 
*RTEMS*, one
or more component names, and a 3-digit number which reflects the 
hierarchy of
requirements.  Each part is separated by a "-" character.  For example UIDs
from RTEMS-Classic-Task-001 to RTEMS-Classic-Task-999 are task requirements,
UIDs from RTEMS-Classic-Semaphore-001 to RTEMS-Classic-Semaphore-999 are
semaphore requirements, UIDs from RTEMS-Classic-MQ-001 to 
RTEMS-Classic-MQ-999
are message queue requirements, etc.  The benefit is that requirement 
files are
organized in directories.

.. topic:: Doorstop

     Doorstop uses documents to create namespaces (named a prefix in 
Doorstop).
     For the example above, you can create the documents like this:

     .. code-block:: none

         doorstop create -d 3 RTEMS-Classic -p RTEMS reqs/classic
         doorstop create -d 3 RTEMS-Classic-Task -p RTEMS-Classic 
reqs/classic/task
         doorstop create -d 3 RTEMS-Classic-Semaphore -p RTEMS-Classic 
reqs/classic/semaphore
         doorstop create -d 3 RTEMS-Classic-MQ -p RTEMS-Classic 
reqs/classic/mq


-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.