Re: [tag] Comments on Guidelines 1.0.8.3

[Stephen Green <stephen.green@documentengineeringservices.com>]

A comment on 'Variables' inline below.

Also, there's a small typo I should fix in 3.1 first sentence in
"General Semantics..." (missing 'to' in 'shall apply to...')
and in 4.2 last sentence there seems to be missing some
normative language so that "When the prerequisite evaluates
to false then the predicate <<shall? should?>> not be evaluated".

Best regards
---
Stephen D Green




2009/10/27 Jacques R. Durand <JDurand@us.fujitsu.com>:
> My editorial comments on rev 1.0.8.3, which otherwise looks quite fine to
> me:
>
>
> - Section 1.4: since the doc is normative, and defines a TA model, we should
> introduce as:
> "This document is a guide to test assertions and also defines a general test
> assertion model."
> instead of just:
> "This document is a guide to test assertions."
>
> - remove the "(normative)" addition to several level 1 titles, since we
> specify at the beginning of the Introduction that
> "All text is normative unless otherwise indicated"
>
> - should we say a word about "Variables" in the listing of optional TA
> parts, section 3.1?

<steve>
maybe we could add another optional part 'Variable' and ensure the text
is consistent with the 'Variable' entry in the Glossary
or
we could just remove 'Variable' from the Figure 4 (as it is introduced later
as a more advanced feature)

</steve>


>
> - section 3.2: suggest to introduce Figure 4 as:
> "Figure 4 shows a more formal model of a test assertion, that will be
> described later in more details."
>
> - section 4.11: the last example of TA as it relates to "requirement #400"
> that targets "gizmo", should replace "widget" with "gizmo" in its Target.
> Same in the comments just before and after.
>
> - Section 5 (glossary): Prescription levels need to extend to ISO keywords
> ("shall"...). See at the end of this email.
> Should we also - in the Introduction - mention that all examples are using
> RFC2119 keywords more common in OASIS specifications, but that such examples
> would work as well if the "example normative statements" had used ISO
> keywords instead, e.g. SHALL instead of MUST.
>
> - Section 6: conformance clause:
> Suggest to expand to:
> "Implementations subject to conformance are representations of the test
> assertion model described in Section 3.
> In order to conform to this guidelines, a test assertion representation
> shall:
> (1) contain all mandatory parts defined in Section 3.1.
> (2) use names for these parts that are identical or can be unambiguously
> mapped to the definitions used in 3.1 as well as in section 5 (glossary).
> (3) when using optional parts defined in section 3.1, use names that are
> identical to or can be unambiguously mapped to these definitions .
> (4) When using advanced features defined in section 4, i.e. any of the
> following: complex predicate, prerequisite, TA related to a property,
> references to other TAs, references to external specifications, inclusion of
> normative statements, versioning, variables, target categories related to
> each other, then a conforming TA representation shall use these features in
> accordance with the best practice or at least not in violation of these best
> practices, and with the semantics described in Section 4 and 5 or at least
> not conflicting with it (e.g. augmenting the original semantics, but not
> overriding it).
>
> Mandatory statements are designated by the keyword 'shall' and 'shall not'
> in bold type, as described in Annex H of [ISO/IEC Directives] ."
>
>
> - in the "TA for Dummy Widget" appendix:
> Add a couple of TAs that show different target types, e.g. those defined at
> the end of 4.11 ("gizmo", "switch")
>
>
> -jacques
>
> ===============================================
>
>
> The ISO keywords:
> --------------------------
>
> SHALL – to indicate requirements strictly to be followed in order to conform
> to the standard and in which no deviation is permitted.  Equivalent
> expressions include: is to, is required to, has to, it is necessary. Do not
> use MUST as an alternative for shall.
>
> SHALL NOT - converse of SHALL.
>
> SHOULD – to indicate that among several possibilities one is recommended as
> particularly suitable, without mentioning or excluding others.
>
> SHOULD NOT – converse of SHOULD.
>
> MAY – to indicate a course of action permissible within the limits of the
> standard.   Equivalent expressions include: is permitted, is allowed.
>
> NEED NOT – to indicate a course of action is not required.
>
> CAN – statement of possibility and capability, whether material, physical,
> or causal.  Equivalent expressions include: be able to, it is possible to.
>
> CANNOT – converse of CAN.
>
>
>
> The definitions from RFC 2119 are given below, and have been
> simplified (taken from the OASIS Conformance Guidelines whcih should be
> quoted) to highlight all the keywords:
>
> -----------------------------------------------------------------------------------------------------------------------
>
> MUST - the requirement is an absolute requirement of the specification.
>
> MUST NOT – the requirement is an absolute prohibition of the specification
>
> REQUIRED – see MUST
>
> SHALL – see MUST
>
> SHALL NOT – see MUST NOT
>
> SHOULD – there may exist valid reasons in particular circumstances to ignore
> a particular item, but the full implications must be understood and
> carefully weighed before choosing a different course.
>
> SHOULD NOT – there may exist valid reasons in particular circumstances when
> the particular behavior is acceptable or even useful, but the full
> implications should be understood and the case carefully weighed before
> implementing any behavior described with this label.
>
> RECOMMENDED – see SHOULD.
>
> MAY - the item is truly optional.  One vendor may choose to include the item
> because a particular marketplace requires it or because the vendor feels
> that it enhances the product while another vendor may omit the same item.
> An implementation that does not include a particular option MUST be prepared
> to interoperate with another implementation that does include the option,
> though perhaps with reduced functionality. In the same vein an
> implementation, which does include a particular option MUST be prepared to
> interoperate with another implementation that does not include the option
> (except, of course, for the feature the option provides).