[PATCH 1/4] eng: Update EARS syntax
sebastian.huber at embedded-brains.de
Thu Mar 18 05:50:49 UTC 2021
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:
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
>> +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:
>> -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
.. code-block:: yaml
- role: interface-function
ctx->status = rtems_timer_create( ctx->name, ctx->id );
The link to the :c:func:`rtems_timer_create` interface specification
the ``interface-function`` link role defines the trigger. The
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?
embedded brains GmbH
Herr Sebastian HUBER
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:
More information about the devel