sdo message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: RE: [sdo] ISSUE 164: SDO Compliant Documentation
- From: Bryan Aupperle <aupperle@us.ibm.com>
- To: sdo@lists.oasis-open.org
- Date: Mon, 17 Aug 2009 08:45:31 -0400
Correct use of MAY is to identify optional
support. Good examples would be the statements that an implementation
MAY support the old namespaces. You are correct that we cannot really
test these, but they still define allowed behavior and are still considered
normative .
I agree with you about needing to rework
the MAY throw an exception text.
Your comment about the API points out
another missing piece of the spec. (I was going to raise this issue once
we were more or less finished with the RFC 2119 work). The OASIS
template requires a Conformance section as the last numbered section of
a spec. This section is generally pretty short and identifies each
conformance target and what a target must do to be able to claim to conform
to the specification. This would take the form:
An implementation conforms to this specification
if it meets these conditions:
1. It MUST
comply with all statements in Appendix X, notably all mandatory statements
have to be implemented.
2. It
MUST implement the SDO API defined in section XYZ.
...
The numbered statements here are conformance
clauses, not normative statements and thus are not labeled or added to
the normative statement table.
Bryan Aupperle, Ph.D.
STSM, WebSphere Enterprise Platform Software Solution Architect
Master Inventor
Research Triangle Park, NC
+1 919-254-7508 (T/L 444-7508)
Internet Address: aupperle@us.ibm.com
From:
| "Barack, Ron" <ron.barack@sap.com>
|
To:
| Bryan Aupperle/Raleigh/IBM@IBMUS
|
Cc:
| <sdo@lists.oasis-open.org>
|
Date:
| 08/16/2009 05:03 AM
|
Subject:
| RE: [sdo] ISSUE 164: SDO Compliant
Documentation |
Hi Bryan,
Thanks for reviewing the document.
I'm not sure how MAY's can be normative...after all, they are explicitly
saying we cannot test for the behavior. But in any case, all the
text having to do with "MAY throw an exception" is really just
a waste of space. I mean, what does it tell the user when we say
that an implementation MAY throw an exception, but, on the otherhand, it
may accept the input?
Another point is that I removed
MUSTs from lines like "the getRootObject method MUST return the root
object." I think we need some kind of text that says the API
has to be fully implemented, and the normative statements in the docu go
beyond the behavior described in the javadoc..." otherwise the spec
just becomes too unreadable.
At least, that was my reasoning.
I guess this will all be discussed on Tuesday's meeting. Have
fun! I'll be in Barcelona :-)
Ron
From: Bryan Aupperle [mailto:aupperle@us.ibm.com]
Sent: Freitag, 14. August 2009 19:44
To: Barack, Ron
Cc: sdo@lists.oasis-open.org
Subject: Re: [sdo] ISSUE 164: SDO Compliant Documentation
Lines with MAYs that need review:
There is a set dealing with throwing exceptions (380, 413, 549, 553, 554,
1013, 1628 and 1648). While these are OK, there may be a better way
to discuss error handling once and not have all of these individual MAYs.
There is a set dealing with the language specs (244, 245, 263 and 264).
Unless we make language specifications conformance targets (not the
SCA pattern), we need reword these.
711-713 and 1488-1489 should be reworded.
Ones that are not really normative statements: 130, 335, 421 (lower case),
491, 672, 844, 1011, 1161 (lower case), 1567 (lower case), 2114&2115,
2201 (lower case).
2343 has a wording problem
Bryan Aupperle, Ph.D.
STSM, WebSphere Enterprise Platform Software Solution Architect
Research Triangle Park, NC
+1 919-254-7508 (T/L 444-7508)
Internet Address: aupperle@us.ibm.com
From:
| "Barack, Ron" <ron.barack@sap.com>
|
To:
| <sdo@lists.oasis-open.org>
|
Date:
| 08/14/2009 09:45 AM
|
Subject:
| [sdo] ISSUE 164: SDO Compliant
Documentation |
Hi Everyone,
As discussed, I've created a JIRA issue to
discuss this:
http://www.osoa.org/jira/browse/SDO-164
As promised, I've uploaded a first pass at
the core spec here: http://www.oasis-open.org/apps/org/workgroup/sdo/download.php/33803/sdo-core-090814.doc
The version has an appendix where the compliance
points are listed, with links to the relevant sections of the spec…I believe
that this is what Brian was referring to when he said we should copy what
was done in the SCA assembly TC.
I've used the keyword MUST to indicate a compliance
point for the implementation. I tried to keep these limited to stuff
for which I could imagine writing a test. For constraints on application,
I used "requires". I noticed that the SCA spec also has
compliance points on things like the SCDL files, so it seemed OK to use
2119 language here. The appendix contains only MUSTS.
Of course I had to make a bunch of editorial
changes, and as I was going thru I reworked some paragraphs that I thought
were unclear. I tried not to alter the meaning of anything, only
to clarify, but this requires everyone review the changes. The only
big change was that I removed section 4.2.7, on change summary serialization,
to chapter 11 (ChangeSummary XML Format).
Best Regards,
Ron
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]