OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

sca-bindings message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Use of Related Work block for referencing test case artefacts etc[was Re: Handling external...]



Narrowly on this point (from 10 Feb 2011 [1]):

"With regard to the specific link from the JMS and WS test
case documents to the test case artefacts I believe this
is a general issue for all the SCA specs, and that Anish
Karmarkar has taken that issue forward with you, we are
awaiting a response so that the TC knows what actions, if
any, it needs to take to update these documents to include
the references."

1. I think I have answered the question posed by Anish,
    viz., whether specification cover pages can be updated
    after publication to include missing items in the
    Related Work section.  The answer was "no, don't
    think so..."  See [1] below for details.

2. Anish further clarified that

    "we found few more minor corrections that we have to
     make to the testcase document => we would need another
     CSD/PR regardless of the cover page issue..."

With respect to the general matter of providing references
to test suites (ZIP files) and similar artifacts, my general
advice has been, and still is: use the Related Work block.

That is, at this moment (under current TC Process rules for
allowed changes), I don't have any guidance in addition to
what I recommended earlier [2].  Part-whole relations are
valid for the Related Work block, as discussed below.
When an associated test suite is not a "part" but a
separate Work Product, use of a Related Work reference is
also recommended.

This is mostly still applicable:
http://docs.oasis-open.org/specGuidelines/namingGuidelines/metadata.html#relatedWork

  relation hasPart: The described resource includes the
       referenced resource either physically or logically
  relation isPartOf: The described resource is a physical
       or logical part of the referenced resource

So I'll summarize: when a TC needs to provide an updatable and
visible reference (URI reference) for any part of a multi-part
specification (e.g., schemas that are in separate files,
test cases that are distributed in a ZIP file as part of the
Work Product release), the section "Related Work" on the
prose specification cover page provides a natural location
for referencing these "parts".   Since the spec cover page
is edited by TC Admin, adjustments can be made at publication
time to ensure that the URI references are consistent (and
that is an "allowed change" on the cover page).  If the
additional (artifacts, machine-readable files) materials
are stored in a subdirectory (recommended) or in a ZIP file,
providing a URI reference is straight-forward.  TC Admin
does not (now) have bandwidth or mandate to edit the
References or other sections of a specification, so
using the Related Work block is recommended.

Similarly, in cases where one specification has a dependency
upon some *other* Work Product, or a natural affiinity, or
a peer relationship, making reference to the other Work
Product in the Related Work block is motivated, and advised.
Any specification should clearly identify its "parts"
if it is a multi-part work, and provide a clear means of
making URI references to the various parts from the parts.

==============================================================
Key statements about Work Product "parts"
==============================================================

A. TC Process

http://www.oasis-open.org/committees/process-2010-07-28.php#quality-multiPart
"(5) Multi-Part Work Products.
A Work Product may be composed of
any number of files of different types,
though any such multi-part Work Product
must have a single Work Product name and
[must have a single Work Product] version number.
Irrespective of the number [of parts] and
[Irrespective of the] status of the constituent parts,
the Work Product as a whole
must be approved by a single Work Product Ballot.

B. TC Handbook

http://docs.oasis-open.org/TChandbook/Reference/WPQualityRequirements.html

- "The Work Product, even if multi-part, must have a single name
   and version number, and must be approved at each stage by a
   single Work Product Ballot"

- "the constituent parts cannot advance independently of each other"

- "In the case of multiple prose documents, there should be a single
   primary prose document that then refers to the distinct parts"

-  "Each distinct part should clearly state that it is part of the
   Work Product and refer to both the top-level document and any
   other related prose documents." [example follows]

==================================================================

URIs for related Work items can be provided by the spec editors (when Word
Processor files are used) in the Custom Properties
of the editable source file.  Under current practice,
the spec editors will also enter information about Related
Work items in the submission form for a e.g., CSD publication
or Puvlic review

http://marypmcrae.com/csd-creation-request

"Please provide a link to a zip file containing all of the necessary resources 
including the editable source of the working draft and any related resources 
such as namespace documents or schema files..."

In the act of publication, TC Admin can negotiate or
clarify any details that may not be clear in the
submitted form for Related Work items.

  Best wishes,

- Robin

==================== References:


[1] Wed, Feb 9, 2011 at 7:56 AM
     subject Re: Question about updating the cover page of a PR spec

[Robin wrote]

I've made an initial investigation into the request to change the
cover pages for the CSPRD01 specification
"sca-j-pojo-ci-1.1-testcases-1.0-csprd01".

While I understand the TC's desire to see the document for
the ZIP file referenced on the cover pages, I don't see how
I can do that retrospectively, after the PR announcement,
after publication of the PR documents, and after completion
of the public review where the document was in view.

In principle, I don't think the cover pages of specifications
should be changed after the fact, unless in the rare case
where it could be proven that a publisher (e.g.,) made a
typo, or something similar, in the very act of publishing
as an operational gesture.  When you say it's "missing"
I do not understand this to be such a publishing error.

There are lots of critical facts in this case, but among
them is that the public review was completed, and
for the sake of that public review, any reviewer did not see
the Related Work.  Had the reference been visible, someone
might have assumed (or wondered, or asked) whether
the content in the ZIP file was part of the "SCA-J POJO
Component Implementation v1.1 TestCases Version 1.0"
Work Product under review.  But the reviewers did not
have the "Related Work" reference in view, so perhaps
they did not consider whether there might be more to the
review than just the prose specification being viewed.
So how can we go back and pretend that they saw
the reference to the ZIP file?

I might be persuaded to think about this differently, but
as a matter of principle, I do not think we can change the
spec to add "Related Work" references after a public review
  -- by changing the cover pages of a document to purport
that something not seen for review was seen for review.

I am sympathetic with the TC's desire not to have
additional reviews, but I think in this case (independent of
the above), there are actually several reasons to do so.

For example, the CSPRD01 says in the Abstract:

"This document defines the TestCases for the SCA Assembly
specification"  -- but in the [Normative] References section
(1.4 Normative References, 1.5 Non-normative References),
the SCA Assembly specification is not cited.

Similarly, in the "Related Work" section of the PR, the
SCA Assembly specification is not named as a related
work.

Thanks,

Robin

=========

[2] http://lists.oasis-open.org/archives/sca-bindings/201101/msg00013.html




Robin Cover
Interim TC Administrator
OASIS, Director of Information Services
Editor, Cover Pages and XML Daily Newslink
Email: robin@oasis-open.org
Staff bio: http://www.oasis-open.org/who/staff.php#cover
Cover Pages: http://xml.coverpages.org/
Newsletter: http://xml.coverpages.org/newsletterArchive.html
Tel: +1 972-296-1783


On Tue, 1 Mar 2011, Simon Holdsworth wrote:

> Robin,
> 
> Following up on this query I wanted to pull out the specific question:
> 
> Can we have a designated cross reference in an OASIS specification to an external standards document, in particular an IETF
> specification, which is pending final standardisation?
> 
> The specific example of this described is the JMS binding specification and test assertions which refer to the current IETF
> JMS URI specification which is in the process of being standardised but which may not complete standardisation before the JMS
> binding documents, and whose URL will change when it becomes a standard.  We would like to avoid the need to revise and
> re-review the JMS binding specifications when the IETF standardisation process completes.
> 
> Thanks, Simon
> 
> Simon Holdsworth
> STSM, SCA Bindings Architect; Master Inventor; OASIS SCA Bindings TC Chair, AT&T and Boeing Lab Advocate
> MP 211, IBM UK Labs, Hursley Park, Winchester SO21 2JN, UK
> Tel +44-1962-815059 (Internal 245059) Fax +44-1962-816898
> Internet - Simon_Holdsworth@uk.ibm.com
> 
> __________________
> 
> Robin,
> 
> With regard to the specific link from the JMS and WS test case documents to the test case artefacts I believe this is a
> general issue for all the SCA specs, and that Anish Karmarkar has taken that issue forward with you, we are awaiting a
> response so that the TC knows what actions, if any, it needs to take to update these documents to include the references.
> 
> We have a second concern regarding links, this one is from the JMS Binding Specification [1] and JMS Binding Test Assertions
> Specification [2] to the IETF JMS URI specification [3] (designated by the [IETFJMS] normative reference, with associated
> footnote).  The IETF specification is in the process of being standardised, but is currently still in an editors draft state.
>  The JMS Binding and Test Assertion Specifications refers to a specific draft, of which there is a more recent version, with
> no changes relevant to its use in the OASIS specifications.
> 
> [1]http://www.oasis-open.org/apps/org/workgroup/sca-bindings/download.php/40397/docs.oasis-open.orgopencsasca-bindingssca-jmsbinding-1.
> 1-spec-csprd03.html
> [2]http://www.oasis-open.org/apps/org/workgroup/sca-bindings/download.php/40393/docs.oasis-open.orgopencsasca-bindingssca-jmsbinding-1.
> 1-test-assertions-1.0-csd01.html
> [3] http://tools.ietf.org/id/draft-merrick-jms-uri-09.txt
> 
> The question is whether there is some way to handle this external specification dependency in a way that does not require us
> to formally revise/re-review the JMS binding when the IETF specification becomes a standard (expected timeframe for that is
> about 4 months), possibly via a designated cross-reference?  The main concern here is whether a move to Committee
> Specification for these two OASIS specifications would then mean additional impacts/work to update the reference when the
> IETF standardisation process completes and the final URL is available.
> 
> Thanks, Simon
> 
> Simon Holdsworth
> STSM, SCA Bindings Architect; Master Inventor; OASIS SCA Bindings TC Chair, AT&T and Boeing Lab Advocate
> MP 211, IBM UK Labs, Hursley Park, Winchester SO21 2JN, UK
> Tel +44-1962-815059 (Internal 245059) Fax +44-1962-816898
> Internet - Simon_Holdsworth@uk.ibm.com
> 
> 
> 
> From:        Robin Cover <robin@oasis-open.org>
> To:        SCA Bindings TC List <sca-bindings@lists.oasis-open.org>
> Cc:        Bryan Aupperle <aupperle@us.ibm.com>, Martin Chapman <MARTIN.CHAPMAN@oracle.com>, Robin Cover
> <robin@oasis-open.org>
> Date:        21/01/2011 20:06
> Subject:        Re: [sca-bindings] Missing links in test case documents
> 
> ____________________________________________________________________________________________________________________________________
> 
> 
> 
> [Bryan said, in part]
> 
> > I noticed that the test case
> > documents for both the WS binding and the JMS binding do not have links to
> > the respective test artifacts zips files.  This means the reader really has
> > no way to know these zip files exist or where to find them.
> 
> [Martin replied]
> On Fri, Jan 21, 2011 at 11:08 AM, Martin Chapman
> <MARTIN.CHAPMAN@oracle.com> wrote:
> > Bryan,
> > Good observation. I?m not sure ?related work? is the right way to do this
> > since the zip files are actually part of the same work product. The TC
> > process does require a reference to these files without saying how! I have
> > copied Robin since there was confusion over the Policy spec and he may have
> > suggestions for doing this in a better way. I will also leave it to his
> > judgement as to whether this would warrant a public review, since it is only
> > making an implicit link explicit.
> >
> > Martin.
> 
> I agree with Martin's (implicit) doubt about the "right" or "best" way
> to fulfill the terms of the TC Process [1] and (more importantly) to
> help make readers/users aware of all essential "parts" in a
> multi-part work [2].
> 
> I don't think it's wrong to use the "Related Works:" block on a
> spec cover page for citation of a discrete work sub-part that
> merits special attention.  This was anticipated and recommended
> in the Naming Guidelines document [3] ("OASIS Naming Guidelines
> Part 2: Metadata and Versioning") that's no longer the latest
> reference for guidance, but was consistent with other instructions
> available from the OASIS Library /templates/ area.  I think that
> guidance is still applicable.
> 
> In particular, we have recommended consideration of the DCMI
> relational terms in the "Related Works:" block, including
> the following relations for part-whole:
> 
> hasPart:  The described resource includes the referenced
>              resource either physically or logically
> isPartOf: The described resource is a physical or logical
>              part of the referenced resource
> 
> And so, several OASIS TCs have used  "Related Works" to reference
> parts of a whole (parent to children), or sibling parts, including
> "parts" that instantiate XML schemas, ontologies, and other
> machine readable files or packages.
> 
> See for example, "Related Work" in the recent OASIS
> OpenDocument specification:
> 
> http://docs.oasis-open.org/office/v1.2/csprd02/OpenDocument-v1.2-csprd02.html
> 
> Related Work:
> This specification consists of this document as well as the
> following documents, schemas and ontologies:
> 
> OpenDocument v1.2 part 1: OpenDocument Schema
> OpenDocument v1.2 part 2: Recalculated Formula (OpenFormula) Format
> OpenDocument v1.2 part 3: Packages
> OpenDocument v1.2 Relax NG Schema (.rng)
> OpenDocument v1.2 Manifest Schema  (.rng)
> OpenDocument v1.2 Digital Signature Schema  (.rng)
> OpenDocument v1.2 Metadata Manifest Ontology  (.owl)
> OpenDocument v1.2 Package Metadata Manifest Ontology  (.owl)
> 
> I'm planning to schedule some new work to study this topic (once
> the backlog of regular TC Admin support issues is handled).
> 
> Cheers,
> 
> - Robin
> 
> PS No interpretation just yet about additional public review as
> possibly occasioned by the suggested change.
> 
> [1] http://www.oasis-open.org/committees/process-2010-07-28.php#quality-formalLangDefns
> 
> [with respect to] "normative computer language definitions
> that are part of the Work Product, such as XML instances,
> schemas... Each text file must be ***referenced from*** the Work Product..."
> 
> Ignoring the awkwardness of saying (a) that schemas are
> "part of the Work Product" and that (b) they must be
> "referenced from the Work Product"   -- apparently requiring that
> the latter use mean "from the relevant prose part(s) of the
> the Work Product, more immediately visible than the non-prose
> parts of the Work Product -- it's not clear by what means the
> CLDs are to be "referenced from" the (prose part(s) of) the Work
> product.
> 
> TCs do want more guidance.  In the previous [pre-October-15]
> version of the Naming Guidelines, some discussion was
> presented about non-prose artifacts that are parts of multi-part
> works, but this content was not brought forward, and needs to be
> reworked in a Naming Directives document update, and maybe
> in spec templates.
> 
> [2] http://www.oasis-open.org/committees/process-2010-07-28.php#quality-multiPart
> 
> [3] http://docs.oasis-open.org/specGuidelines/namingGuidelines/metadata.html#relatedWork
> 
> Excerpt:
> 
> "Within a prose specification title "page", TC editors should
> supply the title and applicable URI for any other resource
> closely associated with the specification, where reference to
> the related resource is deemed essential or strongly motivated.
> In most cases, the TC editors are to make a judgment,
> necessarily subjective, as to whether a Related Work reference
> would be of significant benefit to the human reader.
> 
> Informally (not with an intent to formally implement DCMI
> metadata models), OASIS TC editors may wish to study the
> collection of Dublin Core Metadata Initiative (DCMI) terms
> defined as element refinements of DCMI relation
> [label Relation] --- as these may prompt ideas for Related
> Work candidate references. In DCMI, a relation stores
> "a reference to a related resource... Recommended best
> practice is to reference the resource by means of a string
> or number conforming to a formal identification system."
> Here are some of the element refinements build from DCMI
> relation, usually reciprocal...
> 
> >
> >
> >
> > From: Bryan Aupperle [mailto:aupperle@us.ibm.com]
> > Sent: 21 January 2011 15:05
> > To: sca-bindings@lists.oasis-open.org
> > Subject: [sca-bindings] Missing links in test case documents
> >
> >
> >
> > I bring this up somewhat reluctantly since it could force additional 15-day
> > public reviews.
> >
> > While researching an issue in the Java TC, I noticed that the test case
> > documents for both the WS binding and the JMS binding do not have links to
> > the respective test artifacts zips files.  This means the reader really has
> > no way to know these zip files exist or where to find them.
> >
> > The assembly and policy test case documents have links in the Related Work
> > section of the front matter.  For example, from the assembly document:
> >
> > The Test Suite artifacts relating to this document can be found here:
> > http://docs.oasis-open.org/opencsa/sca-assembly/sca-assembly-1.1-testcases-cd03.zip
> >
> > We probably should add these links.
> >
> > Bryan Aupperle, Ph.D.
> > STSM, WebSphere Enterprise Platform Software Solution Architect
> > WW Center of Excellence for Enterprise Systems & Banking Center of
> > Excellence Application Integration Architect
> >
> > Research Triangle Park,  NC
> > +1 919-254-7508 (T/L 444-7508)
> > Internet Address: aupperle@us.ibm.com
> 
> 
> 
> --
> Robin Cover
> OASIS, Director of Information Services
> Editor, Cover Pages and XML Daily Newslink
> Email: robin@oasis-open.org
> Staff bio: http://www.oasis-open.org/who/staff.php#cover
> Cover Pages: http://xml.coverpages.org/
> Newsletter: http://xml.coverpages.org/newsletterArchive.html
> Tel: +1 972-296-1783
> 
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
> 
> 
> 
> 
> 
> ____________________________________________________________________________________________________________________________________
> 
> 
> Unless stated otherwise above:
> IBM United Kingdom Limited - Registered in England and Wales with number 741598.
> Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU
> 
> 
> 
> 
> 
> 
> 
> 
> 
> ____________________________________________________________________________________________________________________________________
> 
> 
> Unless stated otherwise above:
> IBM United Kingdom Limited - Registered in England and Wales with number 741598.
> Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU
> 
> 
> 
> 
> 
> 
> 
>


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]