Seems to make sense to me. I noted just a few very small grammatical errors.
On Wed, Jul 24, 2019 at 7:45 AM Sebastian Huber <sebastian.hu...@embedded-brains.de> wrote: > > --- > 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 "To prevent" > +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 "is derived" > + 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 is "derived"? or "is normative"? > + 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 "to be" > +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 _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
