[PATCH 1/4] eng: Update EARS syntax

[Sebastian Huber]

On 18/03/2021 01:43, Chris Johns wrote:

> On 18/3/21 4:34 am, Sebastian Huber wrote:
>> The document used the EARS syntax from 2009 which slightly changed in
>> 2016, see "Listens Learned (8 Lessons Learned Applying EARS)".  The
>> optional pre-conditions moved to the state-driven pattern.  This refined
>> syntax fits better to the action requirements.
>>
>> Update #3715.
>> ---
>>   eng/req/howto.rst       | 38 +++++++++++++++++++-------------------
> The following seems like a formal specification and the section is "How to". Is
> the section really "Specification", that is specification of requirements?

This how-to section should help to write items of this type:

https://docs.rtems.org/branches/master/eng/req/items.html#spectypeactionrequirementitemtype

Action requirement items are a generator for event-driven requirements.

>
>>   eng/req/req-for-req.rst | 30 ++++++++++++++++++++----------
>>   2 files changed, 39 insertions(+), 29 deletions(-)
>>
>> diff --git a/eng/req/howto.rst b/eng/req/howto.rst
>> index 8481214..ee239d4 100644
>> --- a/eng/req/howto.rst
>> +++ b/eng/req/howto.rst
>> @@ -285,18 +285,18 @@ Action Requirements
>>   
>>   Use :ref:`SpecTypeActionRequirementItemType` items to specify and validate
>>   directive calls.  Action requirements are a generator for event-driven
>> -requirements which should be written in the following :ref:`syntax
>> -<ReqEngSyntax>`:
>> +requirements.  Such requirements should be written in the following
>> +:ref:`syntax <ReqEngSyntax>`:
>>   
>> -    *When* <optional preconditions> <trigger>, the <system name> shall
>> -    <system response>.
>> +    **While** <pre-condition>, **while** ..., **when** <trigger>, the <system
>> +    name> shall <system response>.
> Does the special formatting imply something special, ie **While** etc?

Yes, this is the notation used to describe the EARS syntax:

https://alistairmavin.com/ears/

>
>> -The <optional preconditions> are the pre-conditions of the action requirement.
>> -The <trigger> is the action of the action requirement.  The post-conditions
>> -should provide a list of the <system name> shall <system response> clauses.
>> -Each transition in the transition map is an event-driven requirement composed
>> -of the pre-condition states, the action, and the post-condition states defined
>> -by the map entry.
>> +The list of <pre-condition> clauses are the pre-conditions in a particular
> What do the '<' and '>' imply? Should `<pre-condition>` be used?

This was an attempt to explain the relationship between the EARS 
notation and the attributes of the item. I will try to make this more clear.

>
>> +state of the action requirement.  The <trigger> is the action of the action
>> +requirement.  The post-conditions in a particular state provide a list of the
>> +<system name> shall <system response> clauses.  Each transition in the
>> +transition map is an event-driven requirement composed of the pre-condition
>> +states, the action, and the post-condition states defined by the map entry.
> If you inspect the language used in detail you have a <trigger> that is an
> "action" of an "action requirement" however <trigger> is the only piece that has
> any special annotation yet it depends on "action" and "action requirement". In
> the current text "action requirement" is the section so that is OK but it does
> not deal with "action".
In the action code block of the item there may be a bit of code and not 
just a single function call.

In a follow up patch we have:

The trigger of the action requirement is defined by the link to an
:ref:`SpecTypeInterfaceFunctionItemType` or an
:ref:`SpecTypeInterfaceMacroItemType` item using the
:ref:`SpecTypeInterfaceFunctionLinkRole`.

And:

.. code-block:: yaml

     links:
     - role: interface-function
       uid: ../if/create
     test-action: |
       ctx->status = rtems_timer_create( ctx->name, ctx->id );

The link to the :c:func:`rtems_timer_create` interface specification 
item with
the ``interface-function`` link role defines the trigger.  The 
``test-action``
defines the trigger code for the validation test.   The validation test is
defined in this item along with the specification.

>
>>   Use ``CamelCase`` for the pre-condition names, post-condition
>>   names, and state names.  The more conditions a directive has, the shorter
> And to highlight my point is "pre-condition" and "post-condition" actually
> `<pre-condition> and <post-condition>?
No, this text refers to the attributes of the action requirement item.
>
> Is the snake-case for the tags defined and mandated

You mean the item attribute keys?

https://docs.rtems.org/branches/master/eng/req/items.html#name

-- 
embedded brains GmbH
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.huber at embedded-brains.de
phone: +49-89-18 94 741 - 16
fax:   +49-89-18 94 741 - 08

Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/