Change Control Board (CCB) proposal for requirements (v2)

[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

One topic is the Change Control Board (CCB). The Doorstop maintainer was 
not so fond of my idea to add support for digital signatures:

https://github.com/jacebrowning/doorstop/issues/375

So, here is a new proposal without signatures. I think this makes the 
process a bit easier.

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.

-- 
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.