Change Control Board (CCB) proposal for requirements

[Sebastian Huber]

Hello Gedare,

thanks for the review, here is a second version. The final review can 
later when I submit the patch for the RTEMS Software Engineering manual.

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 requirement approvers*: Persons which registered their public 
key in
   the RTEMS project.  They can create approval signatures with their 
private
   key.  Their public key can be used by everyone to verify the approval
   signatures.

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

* Users should be able to register their public key in the RTEMS project to
   become an RTEMS requirement approver.  The RTEMS maintainer decide 
over the
   registration.

* Requirement approvers should be able to attach their approval to
   requirements, test procedures, test cases and justification reports.

* Attaching an approval should be independent of the normal development work
   flow, e.g. it should be possible to commit an approval long after
   requirements are committed.

* Please note that disapproval must be done at the time of the initial patch
   review.  If an approver needs changes in a requirement to approve it, 
then
   the normal development process must be followed, e.g. the approver 
can make a
   patch with the change and send it for review to the developer mailing 
list.

* Other users should be able to figure out which part of RTEMS is 
approved by
   which requirement approver.

* The integrity of approvals should be ensured by digital signatures (PGP).

* Changes in RTEMS should invalidate automatically all approvals which are
   affected by the change (on a best-effort basis).

.. 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.  The service to manage
     approvals can be done with a new Doorstop feature, see
     `#375 <https://github.com/jacebrowning/doorstop/issues/375>`_,


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