Requirement Identifiers

Thu Jul 11 13:19:43 UTC 2019

Early on, we discussed that there wasn't a Rest backend to Doorstop. If we
are having
to add that anyway, can each "category" be generated as a chapter?

We could generate 100+ chapters but we can't have 100+ requirements
documents.

I lean strongly to needing categories of requirements. It would be much
easier
to manage long term if you could easily correlate requirements with
managers,
handlers, libraries, etc.

On Thu, Jul 11, 2019 at 3:15 AM Sebastian Huber <
sebastian.huber at embedded-brains.de> wrote:

> 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.
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20190711/12d4371b/attachment-0002.html>