[PATCH] eng: Add Software Requirements Engineering chapter

[Gedare Bloom]

On Mon, Sep 30, 2019 at 7:13 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> On 24/07/2019 15:44, Sebastian Huber wrote:
> > +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>`_).
>
> In the first version of this patch, the proposal was to use Git to track
> the history of specification items (requirements are a specialization
> them). I think it would be better to add the revision and the
> description of a change directly to the files, e.g. add a custom
> attribute "changes" which contains a list of "revision" and
> "description" tuples.  Revision 1 items do not need this attribute.
> Example:
>
> changes:
> - description: The description of the change from revision 1 (initial) to 2.
>    revision: 2
> - description: The description of the change from revision 2 to 3.
>    revision: 3
> - description: The description of the change from revision 3 to 4.
>    revision: 4
>
> This information can be used to add the change log of each specification
> item to a human readable document for example.  The documentation
> generator program does not need a Git repository in this case to extract
> the information.
>
> Also this way the revision of a specification item is independent of the
> current version control system. This makes it easier to reference items
> of a specific revision. For example: "With ABC-001 in revision 1 we
> could meet our system requirements, however the change to revision 2 is
> a problem, due to ...".
>
It seems to be a matter whether one needs the revision history readily
available without digging through git. Your argument for referring to
revisions, and also to extract them without needing git, is reasonable
to me.  I suspect it should make the release process simpler..

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