tag message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Comments on Guidelines 1.0.8.3
- From: "Jacques R. Durand" <JDurand@us.fujitsu.com>
- To: "TAG TC" <tag@lists.oasis-open.org>
- Date: Mon, 26 Oct 2009 18:14:45 -0700
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?
- 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).
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]