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

Wed Jul 24 23:17:18 UTC 2019

On Wed, Jul 24, 2019 at 1:39 AM Sebastian Huber <
sebastian.huber at embedded-brains.de> wrote:

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

The normal process should be defined and referenced.

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

Different companies and same funding source isn't 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.
>

There is a problem with independence and reasonable time frame. You are
relying on volunteers to review requirements (or anything else) and at
their time
availability mercy. I don't know how you ensure you have proper second
reviewers
from the volunteer community in a reasonable time frame. Lack of commentary
could just mean personal issues or travel. For example, I spent 3 weeks of
June
traveling and/or teaching and was sick enough for two rounds of
antibiotics. I
care about reviewing but I didn't review much last month. And even when I do
review, there is a practical limit.

Some of this going to have to be spoon fed to the community to have a chance
to get it reviewed by volunteer. Better would be paid time from alternative
core
developers to speed this up.But ultimately some core reviewers will be
volunteer
and slow.

A normal timeout isn't appropriate for requirements. They really deserve
positive
acknowledge. A true CCB waits for a majority from a quorum.

A technical part of the solution is be something like Phabricator which
tracks
getting multiple approvals and lets you do online reviews. A tool like this
also
helps with the records for code reviews and approval beyond the final git
log.

>
> For a qualification of RTEMS according to certain standards, the
> requirements
> may be approved by an RTEMS user.

I think you mean tailoring the requirements and code.

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

Careful with approved. Do you mean tailoring again?

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

Determinative doesn't appear to be a word.

>
> .. 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.
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20190724/61f6aad4/attachment-0002.html>