<div dir="ltr">Early on, we discussed that there wasn't a Rest backend to Doorstop. If we are having<div>to add that anyway, can each "category" be generated as a chapter?</div><div><br></div><div>We could generate 100+ chapters but we can't have 100+ requirements documents.</div><div><br></div><div>I lean strongly to needing categories of requirements. It would be much easier</div><div>to manage long term if you could easily correlate requirements with managers,</div><div>handlers, libraries, etc.</div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Jul 11, 2019 at 3:15 AM Sebastian Huber <<a href="mailto:sebastian.huber@embedded-brains.de">sebastian.huber@embedded-brains.de</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hello,<br>
<br>
I work currently on a requirements engineering section for RTEMS in the <br>
RTEMS Software Engineering manual:<br>
<br>
<a href="https://docs.rtems.org/branches/master/eng/index.html" rel="noreferrer" target="_blank">https://docs.rtems.org/branches/master/eng/index.html</a><br>
<br>
The goal is to add a technical specification for a subset of RTEMS. A <br>
technical specification consists of requirements. One basic element is <br>
that requirements can be identified. We have to discuss how requirements <br>
are identified in the RTEMS project.<br>
<br>
The proposed tool to manage requirements in RTEMS is Doorstop:<br>
<br>
<a href="https://github.com/jacebrowning/doorstop" rel="noreferrer" target="_blank">https://github.com/jacebrowning/doorstop</a><br>
<br>
This tool add some restrictions to the way requirements are identified.<br>
<br>
The following text is a part of my requirements engineering draft <br>
document in ReST format.<br>
<br>
Identification<br>
--------------<br>
<br>
Each requirement shall have a unique identifier (UID). The open <br>
question is in<br>
which scope should it be unique? Ideally, it should be universally <br>
unique. As<br>
a best effort approach, the name *RTEMS* shall be used as a part in all<br>
requirement identifiers. This should ensure that the RTEMS requirements <br>
can be<br>
referenced easily in larger systems. The standard ECSS-E-ST-10-06C <br>
recommends<br>
in section 8.2.6 that the identifier should reflect the type of the <br>
requirement<br>
and the life profile situation. Other standards may have other<br>
recommendations. To avoid a bias of RTEMS in the direction of ECSS, this<br>
recommendation will not be followed. In addition, it would also make <br>
the use<br>
of :term:`Doorstop` more difficult, since this tool does not support <br>
attribute<br>
dependent identifiers.<br>
<br>
.. topic:: Doorstop<br>
<br>
The UID of an item (requirement) is defined by its file name <br>
without the<br>
extension. An UID consists of two parts, the prefix and a number. <br>
The parts<br>
are divided by an optional separator. The prefix is determined by the<br>
document to which the item belongs.<br>
<br>
Proposal: Default Doorstop Numbering<br>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br>
<br>
One UID scheme for RTEMS requirements is the concatenation of *RTEMS* and a<br>
5-digit number which is automatically generated by Doorstop. It starts with<br>
RTEMS00001 and ends with RTEMS99999. These identifiers are just unique and<br>
bear no other information.<br>
<br>
Proposal: Number Groups<br>
~~~~~~~~~~~~~~~~~~~~~~~<br>
<br>
Another UID scheme for RTEMS requirements is the concatenation of <br>
*RTEMS* and a<br>
5-digit number which reflects the hierarchy of requirements. For <br>
example UIDs<br>
from RTEMS01000 to RTEMS01999 are task requirements, UIDs from RTEMS02000 to<br>
RTEMS02999 are semaphore requirements, UIDs from RTEMS03000 to <br>
RTEMS03999 are<br>
message queue requirements, etc. It would be also possible to add a <br>
separator<br>
character, for example RTEMS-01234.<br>
<br>
.. topic:: Doorstop<br>
<br>
This is currently not supported by Doorstop, see `issue #349<br>
<<a href="https://github.com/jacebrowning/doorstop/issues/349" rel="noreferrer" target="_blank">https://github.com/jacebrowning/doorstop/issues/349</a>>`_.<br>
<br>
Proposal: Document Hierarchy<br>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br>
<br>
Another UID scheme for RTEMS requirements is the concatenation of <br>
*RTEMS*, one<br>
or more component names, and a 3-digit number which reflects the <br>
hierarchy of<br>
requirements. Each part is separated by a "-" character. For example UIDs<br>
from RTEMS-Classic-Task-001 to RTEMS-Classic-Task-999 are task requirements,<br>
UIDs from RTEMS-Classic-Semaphore-001 to RTEMS-Classic-Semaphore-999 are<br>
semaphore requirements, UIDs from RTEMS-Classic-MQ-001 to <br>
RTEMS-Classic-MQ-999<br>
are message queue requirements, etc. The benefit is that requirement <br>
files are<br>
organized in directories.<br>
<br>
.. topic:: Doorstop<br>
<br>
Doorstop uses documents to create namespaces (named a prefix in <br>
Doorstop).<br>
For the example above, you can create the documents like this:<br>
<br>
.. code-block:: none<br>
<br>
doorstop create -d 3 RTEMS-Classic -p RTEMS reqs/classic<br>
doorstop create -d 3 RTEMS-Classic-Task -p RTEMS-Classic <br>
reqs/classic/task<br>
doorstop create -d 3 RTEMS-Classic-Semaphore -p RTEMS-Classic <br>
reqs/classic/semaphore<br>
doorstop create -d 3 RTEMS-Classic-MQ -p RTEMS-Classic <br>
reqs/classic/mq<br>
<br>
<br>
-- <br>
Sebastian Huber, embedded brains GmbH<br>
<br>
Address : Dornierstr. 4, D-82178 Puchheim, Germany<br>
Phone : +49 89 189 47 41-16<br>
Fax : +49 89 189 47 41-09<br>
E-Mail : <a href="mailto:sebastian.huber@embedded-brains.de" target="_blank">sebastian.huber@embedded-brains.de</a><br>
PGP : Public key available on request.<br>
<br>
Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.<br>
_______________________________________________<br>
devel mailing list<br>
<a href="mailto:devel@rtems.org" target="_blank">devel@rtems.org</a><br>
<a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a></blockquote></div>