---
eng/index.rst | 1 +
eng/req-eng.rst | 813 ++++++++++++++++++++++++++++++++++++++++++++++
images/eng/req-add.pdf | Bin 0 -> 81320 bytes
images/eng/req-add.png | Bin 0 -> 50516 bytes
images/eng/req-add.uml | 40 +++
images/eng/req-modify.pdf | Bin 0 -> 68500 bytes
images/eng/req-modify.png | Bin 0 -> 37776 bytes
images/eng/req-modify.uml | 34 ++
8 files changed, 888 insertions(+)
create mode 100644 eng/req-eng.rst
create mode 100644 images/eng/req-add.pdf
create mode 100644 images/eng/req-add.png
create mode 100644 images/eng/req-add.uml
create mode 100644 images/eng/req-modify.pdf
create mode 100644 images/eng/req-modify.png
create mode 100644 images/eng/req-modify.uml
diff --git a/eng/index.rst b/eng/index.rst
index cfc831b..802eec9 100644
--- a/eng/index.rst
+++ b/eng/index.rst
@@ -26,6 +26,7 @@ RTEMS Software Engineering (|version|)
preface
prequalification
stakeholders
+ req-eng
management
test-plan
test-framework
diff --git a/eng/req-eng.rst b/eng/req-eng.rst
new file mode 100644
index 0000000..6b63c7b
--- /dev/null
+++ b/eng/req-eng.rst
@@ -0,0 +1,813 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2019 embedded brains GmbH
+
+.. |E40| replace:: ECSS-E-ST-40C
+
+.. |E10-06| replace:: ECSS-E-ST-10-06C
+
+Software Requirements Engineering
+*********************************
+
+Software engineering standards for critical software such as |E40| demand that
+software requirements for a software product are collected in a software
+requirements specification (technical specification in |E40| terms). They are
+usually derived from system requirements (requirements baseline in |E40|
+terms). RTEMS is designed as a reusable software product which can be utilized
+by application designers to ease the development of their applications. The
+requirements of the end system (system requirements) using RTEMS are only known
+to the application designer. RTEMS itself is developed by the RTEMS
+maintainers and they do not know the requirements of a particular end system in
+general. RTEMS is designed as a real-time operating system to meet typical
+system requirements for a wide range of applications. Its suitability for a
+particular application must be determined by the application designer based on
+the technical specification provided by RTEMS accompanied with performance data
+for a particular target platform.
+
+Currently, no technical specification of RTEMS exists in the form of a
+dedicated document. Since the beginning of the RTEMS evolution in the late
+1980s it was developed iteratively. It was never developed in a waterfall
+model. During initial development the RTEID :cite:`Motorola:1988:RTEID` and
+later the ORKID :cite:`VITA:1990:ORKID` draft specifications were used as
+requirements. These were evolving during the development and an iterative
+approach was followed often using simple algorithms and coming back to
+optimise. In 1993 and 1994 a subset of pthreads sufficient to support
+:term:`GNAT` was added as requirements. At this time the Ada tasking was
+defined, however, not implemented in GNAT, so this involved guessing during the
+development. Later some adjustments were made when Ada tasking was actually
+implemented. So, it was consciously iterative with the specifications evolving
+and feedback from performance analysis. Benchmarks published from other real
+time operating systems were used for comparison. Optimizations were carried
+out until the results were comparable. Development was done with distinct
+contractual phases and tasks for development, optimization, and the addition of
+priority inheritance and rate monotonic scheduling. The pthreads requirement
+has grown to be as much POSIX as possible. Portability to FreeBSD to use the
+network stack, USB stack, SD/MMC card stack and device drivers resulted in
+another set of requirements. The support for symmetric multiprocessing (SMP)
+was a huge driver for change. It was developed step by step and sponsored by
+several independent users with completely different applications and target
+platforms in mind. The high performance OpenMP support introduced the Futex as
+a new synchronization primitive. A key success element of RTEMS is the ability
+to accept changes driven by user needs and still keep the operating system
+stable enough for production systems. Procedures that place a high burden on
+changes are doomed to be discarded by the RTEMS project. We have to keep this
+in mind when we introduce a requirements management work flow which should be
+followed by RTEMS community members and new contributors.
+
+We have to put in some effort first into the reconstruction of software
+requirements through reverse engineering using the RTEMS documentation, test
+cases, sources, standard references, mailing list archives, etc. as input.
+Writing a technical specification for the complete RTEMS code base is probably
+a job of several person-years. We have to get started with a moderate feature
+set (e.g. subset of the Classic API) and extend it based on user demands step
+by step.
+
+The development of the technical specification will take place in two phases.
+The first phase tries to establish an initial technical specification for an
+initial feature set. This technical specification will be integrated into
+RTEMS as a big chunk. In the second phase the technical specification is
+modified through arranged procedures. There will be procedures
+
+* to modify existing requirements,
+
+* add new requirements, and
+
+* mark requirements as obsolete.
+
+All procedures should be based on a peer review principles.
+
+Requirements for Requirements
+=============================
+
+Identification
+--------------
+
+Each requirement shall have a unique identifier (UID). The 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.
+
+.. 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
+
+The UID scheme for RTEMS requirements is the concatenation of *RTEMS*, one or
+more component names, and a 3-digit number. Each part is separated by a "-"
+character. For example UIDs from RTEMS-Classic-Task-Create-001 to
+RTEMS-Classic-Task-Create-999 are task create requirements, UIDs from
+RTEMS-Classic-Semaphore-Delete-001 to RTEMS-Classic-Semaphore-Delete-999 are
+semaphore delete requirements, etc.
+
+.. 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-Task-Create -p
RTEMS-Classic-Task-Create reqs/classic/task/create
+ doorstop create -d 3 RTEMS-Classic-Semaphore -p RTEMS-Classic
reqs/classic/semaphore
+ doorstop create -d 3 RTEMS-Classic-Semaphore-Delete -p
RTEMS-Classic-Semaphore-Delete reqs/classic/semaphore/delete
+
+ The requirement files are organized in directories.
+
+A initial requirement hierarchy could be this:
+
+* RTEMS
+
+ * Build (Building RTEMS BSPs and Libraries)
+
+ * Config (Application Configuration)
+
+ * Classic
+
+ * Task
+
+ * Create
+ * Delete
+ * Exit
+ * GetAffinity
+ * GetPriority
+ * GetScheduler
+ * Ident
+ * IsSuspended
+ * Iterate
+ * Mode
+ * Restart
+ * Resume
+ * Self
+ * SetAffinity
+ * SetPriority
+ * SetScheduler
+ * Start
+ * Suspend
+ * WakeAfter
+ * WakeWhen
+
+ * Semaphore
+
+ * ...
+
+ * POSIX
+
+ * ...
+
+The specification of the validation of requirements should be maintained also
+by Doorstop. For each requirement document there should be a validation child
+document with a *Test* component name, e.g. RTEMS-Classic-Task-Create-Test. A
+Test component may contain also justifications by design and by analysis, unit
+tests, and integration tests.
+
+Level of Requirements
+---------------------
+
+The level of a requirement shall be expressed with one of the verbal forms
+listed below and nothing else. The level of requirements are derived from RFC
+2119 :cite:`RFC2119` and |E10-06| :cite:`ECSS_E_ST_10_06C`.
+
+Absolute Requirements
+~~~~~~~~~~~~~~~~~~~~~
+
+Absolute requirements shall be expressed with the verbal form *shall* and no
+other terms.
+
+Absolute Prohibitions
+~~~~~~~~~~~~~~~~~~~~~
+
+Absolute prohibitions shall be expressed with the verbal form *shall not* and
+no other terms.
+
+.. warning::
+
+ Absolute prohibitions may be difficult to verify. They should not be used.
+
+Recommendations
+~~~~~~~~~~~~~~~
+
+Recommendations shall be expressed with the verbal forms *should* and
+*should not* and no other terms with guidance from RFC 2119:
+
+ SHOULD This word, or the adjective "RECOMMENDED", mean that there
+ may exist valid reasons in particular circumstances to ignore a
+ particular item, but the full implications must be understood and
+ carefully weighed before choosing a different course.
+
+ SHOULD NOT This phrase, or the phrase "NOT RECOMMENDED" mean that
+ there may exist valid reasons in particular circumstances when the
+ particular behavior is acceptable or even useful, but the full
+ implications should be understood and the case carefully weighed
+ before implementing any behavior described with this label.
+
+Permissions
+~~~~~~~~~~~
+
+Permissions shall be expressed with the verbal form *may* and no other terms
+with guidance from RFC 2119:
+
+ MAY This word, or the adjective "OPTIONAL", mean that an item is
+ truly optional. One vendor may choose to include the item because a
+ particular marketplace requires it or because the vendor feels that
+ it enhances the product while another vendor may omit the same item.
+ An implementation which does not include a particular option MUST be
+ prepared to interoperate with another implementation which does
+ include the option, though perhaps with reduced functionality. In the
+ same vein an implementation which does include a particular option
+ MUST be prepared to interoperate with another implementation which
+ does not include the option (except, of course, for the feature the
+ option provides.)
+
+Possibilities and Capabilities
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Possibilities and capabilities shall be expressed with the verbal form *can*
+and no other terms.
+
+Syntax
+------
+
+Use the Easy Approach to Requirements Syntax (:term:`EARS`) to formulate
+requirements. A recommended reading list to get familiar with this approach is
+:cite:`Mavin:2009:EARS`, :cite:`Mavin:2010:BigEars`, and
+:cite:`Mavin:2016:LLEARS`. Please also have a look at the EARS quick reference
+sheet :cite:`Uusitalo:2012:EARS`. The sentence types are:
+
+* Ubiquitous
+
+ The <system name> shall <system response>.
+
+* Event-driven
+
+ *When* <optional preconditions> <trigger>, the <system name> shall <system
response>.
+
+* State-driven
+
+ *While* <in state>, the <system name> shall <system response>.
+
+* Unwanted behaviour
+
+ *If* <optional preconditions> <trigger>, *then* the <system name> shall
<system response>.
+
+* Optional
+
+ *Where* <feature>, the <system name> shall <system response>.
+
+The optional sentence type should be only used for application configuration
+options. The goal is to use *enabled-by* and *disabled-by* attributes to
+enable or disable requirements based on configuration parameters that define
+the RTEMS artefacts used to build an application executable (header files,
+libraries, linker command files). Such configuration parameters are for
+example the architecture, the platform, CPU port options, and build
+configuration options (e.g. uniprocessor vs. SMP).
+
+Wording Restrictions
+--------------------
+
+The prevent the expression of imprecise requirements, the following terms shall
+not be used in requirement formulations:
+
+* "acceptable"
+* "adequate"
+* "almost always"
+* "and/or"
+* "appropriate"
+* "approximately"
+* "as far as possible"
+* "as much as practicable"
+* "best"
+* "best possible"
+* "easy"
+* "easy"
+* "efficient"
+* "e.g."
+* "enable"
+* "enough"
+* "etc."
+* "few"
+* "first rate"
+* "flexible"
+* "generally"
+* "goal"
+* "graceful"
+* "great"
+* "greatest"
+* "ideally"
+* "i.e."
+* "if possible"
+* "in most cases"
+* "large"
+* "many"
+* "maximize"
+* "minimize"
+* "most"
+* "multiple"
+* "necessary"
+* "numerous"
+* "optimize"
+* "ought to"
+* "probably"
+* "quick"
+* "rapid"
+* "reasonably"
+* "relevant"
+* "robust"
+* "satisfactory"
+* "several"
+* "shall be included but not limited to"
+* "simple"
+* "small"
+* "some"
+* "state-of-the-art".
+* "sufficient"
+* "suitable"
+* "support"
+* "systematically"
+* "transparent"
+* "typical"
+* "user-friendly"
+* "usually"
+* "versatile"
+* "when necessary"
+
+For guidelines to avoid these terms see Table 11-2, "Some ambiguous terms to
+avoid in requirements" in :cite:`Wiegers:2013:SR`.
+
+Separate Requirements
+---------------------
+
+Requirements shall be stated separately. A bad example is:
+
+ RTEMS-001: The task create directive shall evaluate the parameters,
+ allocate a task object and initialize it.
+
+To make this a better example, it should be split into separate requirements:
+
+ RTEMS-001: When the task create directive is called with valid parameters
+ and a free task object exists, the task create directive shall return the
+ identifier of an initialized task object and the RTEMS_SUCCESSFUL status.
+
+ RTEMS-002: If no free task objects exists, the task create directive shall
+ return the RTEMS_TOO_MANY status.
+
+ RTEMS-003: If the id parameter is NULL, the task create directive shall
+ return the RTEMS_INVALID_ADDRESS status.
+
+ RTEMS-004: If the name parameter is not valid, the task create directive
+ shall return the RTEMS_INVALID_NAME status.
+
+ ...
+
+Conflict Free Requirements
+--------------------------
+
+Requirements shall not be in conflict with each other inside a specification.
+A bad example is:
+
+ RTEMS-013: If a mutex is not available, the mutex obtain directive shall
+ enqueue the calling thread on the wait queue of the mutex.
+
+ RTEMS-042: If a mutex is not available, the mutex obtain directive shall
+ return the RTEMS_UNSATISFIED status.
+
+To resolve this conflict, a condition may be added:
+
+ RTEMS-013: If a mutex is not available, when the RTEMS_WAIT option is set,
+ the mutex obtain directive shall enqueue the calling thread on the wait
+ queue of the mutex.
+
+ RTEMS-042: If a mutex is not available, when the RTEMS_WAIT option is not
+ set, the mutex obtain directive shall return the RTEMS_UNSATISFIED status.
+
+Use of Project-Specific Terms and Abbreviations
+-----------------------------------------------
+
+All project-specific terms and abbreviations used to formulate requirements
+shall be defined in the project glossary.
+
+Justification of Requirements
+-----------------------------
+
+The requirements shall have a justification recorded in a dedicated section of
+the requirements file.
+
+Specification Items
+===================
+
+The technical specification of RTEMS will contain requirements, specializations
+of requirements, test procedures, test suites, test cases, and justifications
+by design and by analysis. These things will be called *specification items*
+or just *items* if it is clear from the context.
+
+.. topic:: Doorstop
+
+ Doorstop maintains *items* which are included in *documents*. The normal
+ use case is to store a requirement with meta-data in an item. However,
+ items can be also used to store other things like test procedures, test
+ suites, test cases, and justifications by design and by analysis. Items
+ contain key-value pairs called attributes. Specializations of requirements
+ may contain extra attributes, e.g. interface, build, configuration
+ requirements. All items have the following standard Doorstop attributes:
+
+ active
+ A boolean value which indicates if the requirement is active or not.
+ The value is included in the fingerprint via a document configuration
+ option.
+
+ derived
+ A boolean value which indicates if the requirement derived or not. For
+ the definition of *derived* see the Doorstop documentation. For RTEMS,
+ this value shall be false for all requirements. The value is not
+ included in the fingerprint.
+
+ normative
+ A boolean value which indicates if the requirement derived or not. For
+ the definition of *normative* see the Doorstop documentation. For
+ RTEMS, this value shall be true for all requirements. The value is not
+ included in the fingerprint.
+
+ level
+ Indicates the presentation order within a document. For RTEMS, this
+ value shall be unused. The value is not included in the fingerprint.
+
+ header
+ A header for an item. For RTEMS, this value shall be the empty string.
+ The value is not included in the fingerprint.
+
+ reviewed
+ The fingerprint of the item. Maintain this attribute with the
+ `doorstop clear` command.
+
+ links
+ The links from this item to parent items. Maintain this attribute with
+ the `doorstop link` command. The value is included in the fingerprint.
+
+ ref
+ References to files and directories. See
+ `#365 <https://github.com/jacebrowning/doorstop/issues/365>`_,
+ The value is included in the fingerprint.
+
+ text
+ The item text. The value is included in the fingerprint.
+
+ All items shall have the following extended attributes:
+
+ type:
+ A list of :ref:`item types <ReqEngItemTypes>`. The value is not
+ included in the fingerprint.
+
+ enabled-by:
+ A list of strings which enable the item if a matching configuration
+ option is present. An empty list means the item is unconditionally
+ enabled. The *enabled-by* attribute has a lower priority than the
+ *disabled-by* attribute. The value is included in the fingerprint.
+
+ disabled-by:
+ A list of strings which disables the item if a matching configuration
+ option is present. An empty list means the item is unconditionally
+ disabled. The *disabled-by* attribute has a higher priority than the
+ *enabled-by* attribute. The value is included in the fingerprint.
+
+.. _ReqEngItemTypes:
+
+Item Types
+----------
+
+Specification items can have all sorts of *types*. The selection of types and
the
+level of detail depends on a particular standard and product model. We need
+enough flexibility be in line with ECSS-E-ST-10-06 and possible future
+applications of other standards. Each item may have a list of types.
+Valid types are listed below. This list may change over time. If new types
+are added, then a mapping between types should be specified. The item types
+and their definition is work in progress. A list of types follows:
+
+* functional requirements - Functional requirements shall describe the
behaviour of the
+ software under specific conditions.
+
+ * *application configuration*
+
+ * *function*
+
+ * *operational* - Operational requirements shall
+
+ * define the operation modes (e.g. initialization, multitasking,
termination),
+
+ * describe the operation modes, and
+
+ * describe the operation mode transitions.
+
+* non-functional requirements
+
+ * *application interface*
+
+ * *architecture interface*
+
+ * *build configuration*
+
+ * *constraint*
+
+ * *design*
+
+ * *hardware interface*
+
+ * *maintainability*
+
+ * *performance*
+
+ * *portability*
+
+ * *quality*
+
+ * *reliability*
+
+ * *resource*
+
+ * *tool chain interface*
+
+* *test procedure*
+
+* *test suite*
+
+* *test case*
+
+* *justification by analysis*
+
+* *justification by design*
+
+Build Configuration
+-------------------
+
+Build configuration requirements define what needs to be built (libraries,
+object files, test executables, etc.) and how (configuration option header
+files, compiler flags, linker flags, etc.). The goal is to generate build
+files (Makefile or waf) and content for the Software Configuration File (SCF)
+from it. A YAML scheme needs to be defined for this purpose.
+
+Application Configuration
+-------------------------
+
+Application configuration requirements define the system parameters which can
+be set by the user at link-time. The goal is to generate user manual
+documentation parts and test cases from the application configuration
+requirements. A YAML scheme needs to be defined for this purpose.
+
+Application Interface
+---------------------
+
+Application interface requirements shall describe the interface between the
+software and the application (:term:`API`). The goal is to generate header
+files with Doxygen markup and user manual documentation parts from the
+application interface requirements. A YAML scheme needs to be defined for this
+purpose.
+
+Tool Chain Interface
+--------------------
+
+Tool chain interface requirements shall describe the interface between the
+software and the tool chain libraries (e.g. Newlib, GCC).
+
+Architecture Interface
+----------------------
+
+Architecture interface requirements shall describe the interface between the
+software and the processor architecture (:term:`ABI`).
+
+Hardware Interface
+------------------
+
+Hardware interface requirements shall describe the interface between the
+software and hardware components.
+
+Resources and Performance
+-------------------------
+
+Normally, resource and performance requirements are formulated like this:
+
+* The resource U shall need less than V storage units.
+
+* The operation Y shall complete within X time units.
+
+Such statements are difficult to make for a software product like RTEMS which
+runs on many different target platforms in various configurations. So, the
+performance requirements of RTEMS shall be stated in terms of benchmarks. The
+benchmarks are run on the project-specific target platform and configuration.
+The results obtained by the benchmark runs are reported in a human readable
+presentation. The application designer can then use the benchmark results to
+determine if its system performance requirements are met. The benchmarks shall
+be executed under different environment conditions, e.g. varying cache states
+(dirty, empty, valid) and system bus load generated by other processors. The
+application designer shall have the ability to add additional environment
+conditions, e.g. system bus load by DMA engines or different system bus
+arbitration schemes.
+
+Requirement Traceability
+========================
+
+The standard |E10-06| demands that requirements shall be under configuration
+management, backwards-traceable and forward-traceable.
+
+History of Requirements
+-----------------------
+
+The RTEMS requirements should placed in the RTEMS sources using Git for version
+control. The history of requirements can be traced with Git. Special commit
+procedures for changes in requirement files should be established. For
+example, it should be allowed to change only one requirement per commit. A
+dedicated Git commit message format may be used as well, e.g. use of
+``Approved-by:`` or ``Reviewed-by:`` lines which indicate an agreed statement
+(similar to the
+`Linux kernel patch submission guidelines
<https://www.kernel.org/doc/html/latest//process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes>`_).
+
+Backward Traceability of Requirements
+-------------------------------------
+
+Providing backward traceability of requirements means that we must be able to
+find the corresponding higher level requirement for each refined requirement.
+This is a standard Doorstop feature.
+
+Forward Traceability of Requirements
+------------------------------------
+
+For forward traceability we must find the implementation of each requirement.
+This will be provided through special Doxygen markup.
+
+Requirement Verification
+========================
+
+The verification of each requirement shall be accomplished by one or more of
+the following methods and nothing else:
+
+* *By test*: A test specification is provided to demonstrate that the
requirement
+ is satisfied when the software is executed on the target platform.
+
+* *By design*: A rationale is provided to demonstrate how the qualification
+ requirement is satisfied implicitly by the software design.
+
+* *By analysis*: A statement is provided how the requirement is met, by
analysing
+ static properties of the software.
+
+.. topic:: Doorstop
+
+ For an item in a parent document it is checked that at least one item in a
+ child document has a link to it. For example a child document could
+ contain verification items. With this feature you can check that all
+ requirements are covered by at least one verification item.
+
+Requirement Management
+======================
+
+Change Control Board
+--------------------
+
+Working with requirements usually involves a Change Control Board
+(:term:`CCB`). The CCB of the RTEMS project is the
+`RTEMS developer mailing list
<https://lists.rtems.org/mailman/listinfo/devel>`_.
+
+There are the following actors involved:
+
+* *RTEMS users*: Everyone using the RTEMS real-time operating system to design,
+ develop and build an application on top of it.
+
+* *RTEMS developers*: The persons developing and maintaining RTEMS. They write
+ patches to add or modify code, requirements, tests and documentation.
+
+* *RTEMS maintainers*: They are listed in the
+ `MAINTAINERS <https://git.rtems.org/rtems/tree/MAINTAINERS>`_ file and have
+ write access to the project repositories.
+
+.. TODO: Make a reference to the "normal patch review process".
+
+Adding and changing requirements follows the normal patch review process.
+Reviews and comments may be submitted by anyone, but a maintainer review is
+required to approve *significant* changes. In addition for significant
+changes, there should be at least one reviewer with a sufficient independence
+from the author which proposes a new requirement or a change of an existing
+requirement. Working in another company on different projects is sufficiently
+independent. RTEMS maintainers do not know all the details, so they trust in
+general people with experience on a certain platform. Sometimes no review
+comments may appear in a reasonable time frame, then an implicit agreement to
+the proposed changes is assumed. Patches can be sent at anytime, so
+controlling changes in RTEMS requires a permanent involvement on the RTEMS
+developer mailing list.
+
+For a qualification of RTEMS according to certain standards, the requirements
+may be approved by an RTEMS user. The approval by RTEMS users is not the
+concern of the RTEMS project, however, the RTEMS project should enable RTEMS
+users to manage the approval of requirements easily. This information may be
+also used by a independent authority which comes into play with an Independent
+Software Verification and Validation (:term:`ISVV`). It could be used to
+select a subset of requirements, e.g. look only at the ones approved by a
+certain user. RTEMS users should be able to reference the determinative
+content of requirements, test procedures, test cases and justification reports
+in their own documentation. Changes in the determinative content should
+invalidate all references to previous versions.
+
+.. topic:: Doorstop
+
+ In Doorstop some values of an item (generalization of a requirement)
+ contribute to a
+ `fingerprint of the item
<https://github.com/jacebrowning/doorstop/blob/develop/docs/reference/items.md#reviewed>`_.
+ Changing a value, e.g. the text of a requirement, changes the fingerprint.
+ The links from one item to another include the fingerprint, so the impact
+ of changes is also visible to dependent items. Currently, MD5 is used as
+ the hash. Since this hash is insecure, it is proposed to add a
+ configuration option to Doorstop which enables SHA512 for hashes.
+
+Add a Requirement
+-----------------
+
+.. image:: ../images/eng/req-add.*
+ :scale: 70
+ :align: center
+
+.. _ReqEngModifyRequirement:
+
+Modify a Requirement
+--------------------
+
+.. image:: ../images/eng/req-modify.*
+ :scale: 70
+ :align: center
+
+Mark a Requirement as Obsolete
+------------------------------
+
+Requirements shall be never removed. They shall be marked as obsolete. This
+ensures that requirement identifiers are not reused. The procedure to obsolete
+a requirement is the same as the one to :ref:`modify a requirement
+<ReqEngModifyRequirement>`.
+
+Tooling
+=======
+
+Tool Requirements
+-----------------
+
+To manage requirements some tool support is helpful. Here is a list of
requirements for the tool:
+
+* The tool shall be open source.
+
+* The tool should be actively maintained during the initial phase of the RTEMS
+ requirements specification.
+
+* The tool shall use plain text storage (no binary formats, no database).
+
+* The tool shall support version control via Git.
+
+* The tool should export the requirements in a human readable form using the
Sphinx documentation framework.
+
+* The tool shall support traceability of requirements to items external to the
tool.
+
+* The tool shall support traceability between requirements.
+
+* The tool shall support custom requirement attributes.
+
+* The tool should ensure that there are no cyclic dependencies between
requirements.
+
+* The tool should provide an export to :term:`ReqIF`.
+
+Tool Evaluation
+---------------
+
+During an evaluation phase the following tools were considered:
+
+* `aNimble <https://sourceforge.net/projects/nimble/>`_
+* :term:`Doorstop`
+* `OSRMT <https://github.com/osrmt/osrmt>`_
+* `Papyrus <https://www.eclipse.org/papyrus/>`_
+* `ProR <https://www.eclipse.org/rmf/pror/>`_
+* `ReqIF Studio <https://formalmind.com/tools/studio/>`_
+* `Requirement Heap <https://sourceforge.net/projects/reqheap/>`_
+* `rmToo <http://rmtoo.florath.net/>`_
+
+The tools aNimble, OSRMT and Requirement Heap were not selected since they use
+a database. The tools Papyrus, ProR and ReqIF are Eclipse based and use
+complex XML files for data storage. They were difficult to use and lack good
+documentation/tutorials. The tools rmToo and Doorstop turned out to be the
+best candidates to manage requirements in the RTEMS project. The Doorstop tool
+was selected as the first candidate mainly due a recommendation by an RTEMS
+user.
+
+Tool Candidate - Doorstop
+-------------------------
+
+:term:`Doorstop` has a modern, object-oriented and well-structured
+implementation in Python 3.5 under the LGPLv3 license. It uses a continuous
+integration build with style checkers, static analysis, documentation checks,
+code coverage, unit test and integration tests. In 2019, the project was
+actively maintained. Pull requests for minor improvements were reviewed and
+integrated within days, e.g.
+`#339 <https://github.com/jacebrowning/doorstop/pull/339>`_,
+`#343 <https://github.com/jacebrowning/doorstop/pull/343>`_,
+`#346 <https://github.com/jacebrowning/doorstop/pull/346>`_, and
+`#347 <https://github.com/jacebrowning/doorstop/pull/347>`_.
+Each requirement is contained in a single file in :term:`YAML` format.
+Requirements are organized in documents and can be linked to each other
+:cite:`Browning:2014:RequirementsManagement`.
diff --git a/images/eng/req-add.uml b/images/eng/req-add.uml
new file mode 100644
index 0000000..52b01f0
--- /dev/null
+++ b/images/eng/req-add.uml
@@ -0,0 +1,40 @@
+' SPDX-License-Identifier: CC-BY-SA-4.0
+
+' Copyright (C) 2019 embedded brains GmbH
+
+@startuml
+
+start
+
+:Invoke: ""doorstop add RTEMS"";
+
+note right
+ This will create a new requirement.
+ For this activity its UID shall be NEW.
+ It is located in a file NEW.yml.
+end note
+
+while (Needs a link to a parent requirement?) is (Yes)
+ :Invoke: ""doorstop link NEW PARENT"";
+endwhile (No)
+
+repeat
+ :Invoke: ""doorstop edit NEW"";
+
+ :Edit the requirement according to your needs and save it;
+
+ :Commit NEW.yml with a proper message;
+
+ :Send the patch to the devel@rtems.org mailing list for review;
+repeat while (Reviewers demand changes in the new requirement?) is (Yes)
+->No;
+
+if (New requirement was accepted by reviewers?) then (Yes)
+ :Push the commit to the project repository;
+else (No)
+ :Discard the NEW requirement;
+endif
+
+stop
+
+@enduml
diff --git a/images/eng/req-modify.uml b/images/eng/req-modify.uml
new file mode 100644
index 0000000..cb104a6
--- /dev/null
+++ b/images/eng/req-modify.uml
@@ -0,0 +1,34 @@
+' SPDX-License-Identifier: CC-BY-SA-4.0
+
+' Copyright (C) 2019 embedded brains GmbH
+
+@startuml
+
+start
+
+repeat
+ :Invoke: ""doorstop edit REQ"";
+
+ note right
+ For this activity the UID
+ of the requirement shall be REQ.
+ It is located in a file REQ.yml.
+ end note
+
+ :Edit the requirement according to your needs and save it;
+
+ :Commit REQ.yml with a proper message;
+
+ :Send the patch to the devel@rtems.org mailing list for review;
+repeat while (Reviewers demand changes in the modified requirement?) is (Yes)
+->No;
+
+if (Modified requirement was accepted by reviewers?) then (Yes)
+ :Push the commit to the project repository;
+else (No)
+ :Keep the requirement as is;
+endif
+
+stop
+
+@enduml
--
2.16.4
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
