Re: Filename for POJO testcase PR doc

[Robin Cover <robin@oasis-open.org>]

=== Summary ===

I have investigated the SCA-J TC's question about possible
use of HTTP redirects to correct a few infelicitous URIs
that now incorporate dual versioning elements into some
filenames.  After analysis, I determined that the problem
scope is more far-reaching than initially reported, and
that any "fix" would be limited, since we cannot at the
moment use redirects, and cannot eliminate the bad URIs
and document titles from public view. I therefore offer
for the TC's consideration a proposal to fix the future
but not attempt to fix the past.

=== Details ===

Earlier this month (or several years ago, depending upon
your perspective) Anish made the observation [1] that certain
filenames (URIs) created for the SCA-J TC's specifications
were incorrect according to the new Naming Directives [2]
because the version elements -1.1- and -1.0- were both
included in filenames: "we have a problem that the file
name currently contains two version numbers..."  Mike
Edwards noted that having added a "1.0" tag seems to confuse
things a lot.

Example, where A is attested, B was the suggested
correction, and C is what the Naming Directives
requires [3] based upon a Work Product abbreviation (of)
"sca-j-pojo-ci-testcases":

A: sca-j-pojo-ci-1.1-testcases-1.0-csprd01.pdf
B: sca-j-pojo-ci-testcases-1.1-csprd01.pdf
C: sca-j-pojo-ci-testcases-v1.1-csprd01.pdf

I made initial reply offering 100% agreement with the
TC's concern, noting that someone unfamiliar with the
TC's work would not have much of a clue as to what "1.1"
and "1.0" refer to (as probable versioning/revisioning
identifier components), and indicating my support for
a fix if that was the TC's preference. The infelicitous
filename choice was apparently due to [4] mismatch of
expectations WRT communication with (previous) TC Admin
and no early detection of the bad filenames/URIs when
the specifications were published for Public Review in
November 2010:

http://lists.oasis-open.org/archives/tc-announce/201011/msg00011.html

The specific request from the SCA-J TC was to use HTTP
redirects ["figure out if it is possible to have redirects
from the existing URLs that contain both '1.0' and '1.1'
version numbers, since these URLs have now been published."]

My intent was to investigate the URI design for SCA-J TC
publications so far, with a view to possible use of URI
aliasing mechanisms to clean up the problems from the
past and adjust, as best we can, for improved filenames
going forward.

Of the several URI aliasing mechanisms available to TC Admin
(from a systems POV), use of HTTP Redirect is not one: in
repeated conversations of the past, TC Admin was told that
granting access to Apache server configuration files was too
risky -- because, e.g., regexs can go bad in many ways, creating
infinite loops (server performance problems), etc., and that
there was no IT support for use of redirects in connection
with the OASIS Library. At this moment, OASIS does not have
a full time system administrator (who has handled this level
of URI aliasing in the past).

I agree that HTTP redirects would probably provide the best
mechanisms for some fixes, but unless I try to re-open the
conversation with management and IT, I can't use them. So
I would need to make do with URI rewrites, symlinks, or
other aliasing facilities I can think of.

=== Problem Scope ===

Initially I thought the problem was limited to a few URIs
in connection with the POJO testcase public review document.
It appears that the scope of problem/infelicity is broader:

a) it involves at least twenty-three (23) URIs, for the CSD
    and CSPRD exemplars

b) it involves both the TestCases and Test Assertions
    specifications from the SCA-J TC

c) the issue extends to the published name/title of both
    Work Products as wellas to the URIs

d) the "incorrect" titles and URIs appear in specification
    Normative References sections as well as on document
    cover pages, page footers (etc) and in the OASIS Library
    index view for resource URIs

e) the issue extends to at least thirty (30) URIs for
    specifications developed in the SCA-Bindings TC
    (titles, Normative References, document footers, etc)

SCA-J POJO Component Implementation v1.1 TestCases Version 1.0
Committee Specification Draft 01 /
Public Review Draft 01
8 November 2010
http://docs.oasis-open.org/opencsa/sca-j/sca-j-pojo-ci-1.1-testcases-1.0-csprd01.html

SCA POJO Component Implementation v1.1 Test Assertions Version 1.0
Committee Specification Draft 01 /
Public Review Draft 01
8 November 2010
http://docs.oasis-open.org/opencsa/sca-j/sca-j-pojo-ci-1.1-test-assertions-1.0-csprd01.html

SCA JMS Binding v1.1 TestCases Version 1.0
Committee Specification Draft 01 /
Public Review Draft 01
8 November 2010
http://docs.oasis-open.org/opencsa/sca-bindings/sca-jmsbinding-1.1-testcases-1.0-csprd01.html

SCA JMS Binding Specification v1.1 Test Assertions Version 1.0
Committee Specification Draft 01 /
Public Review Draft 01
8 November 2010
http://docs.oasis-open.org/opencsa/sca-bindings/sca-jmsbinding-1.1-test-assertions-1.0-csprd01.html

=== Provisional Analysis ===

Given that the naming infelicity involves at least two TCs,
at least four different specifications, some 53 URIs (including
directories), work titles, Normative Reference citations,
Citation Format block elements, OASIS Library index pages,
and other elements in published view -- I wonder if the SCA-J
TC members would be willing to simply make changes that
impact the future, rather than trying to repair the past.

Repairing the past would be very costly, as well as risky,
and the remedy would be only partial.

In particular, we are not going to alter published documents
that display the incorrect URIs: multiple approved/published
documents are in now view, displaying the "incorrect" URIs
in many places -- certainly more than 30 instances.  In
the wild we can expect to find dozens of documents and
URI references that use the "incorrect" titles and URIs,
which cannot be changed by OASIS and for which OASIS would
not request changes by external resource owners.

I would recommend this proposal for your consideration:

- make a clean break with the past for specs in the
   SCA-J TC and SCA-Bindings TC which attest the
   duplicate numbering "1.1" and "1.0"

- change the Work Product titles as well as the
   next URIs

- do the same for any other related TCs where the
   dual versioning element problem is attested

- if the next revisions for these specs (or for most
   of them) is -"csd02", then the infelicitous labeling
   can be left behind fairly quickly, art least with
   respect to document cover pages, footers, Normative
   References, Citation Format block, etc. The titles
   and URIs would be correct(ed) at least for these
   upcoming releases, and maybe for others:

   -- csd02
   -- csprd02
   -- cs01
   -- os

- I could explore the possibility of correcting the
   "Latest Version" spec URIs that appears on document
   cover pages so as to migrate to the new URI
   design that avoids both "1.1" and "1.0"


=== Next Steps ===

Please let me know the TC's disposition, ideally in
coordination with members of the SCA-Bindings TC,
where the problem is likewise attested.

Best wishes,

- Robin

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

[1] http://lists.oasis-open.org/archives/sca-j/201102/msg00001.html

[2] Naming Directives on paths/URIs
http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#paths
http://docs.oasis-open.org/[tc-shortname]/[WP-abbrev]/[version-id]/[stage-abbrev][revisionNumber]/[doc-id].[ext]

[3] ND grammar for principal filename:

A filename identifying a specific published instance (stage)
of a Work Product, used in a required cover page URI, must
have the structure
[WP-abbrev]-[version-id]-[stage-abbrev][revisionNumber].[ext],
where [WP-abbrev] is a name under TC control matching the
agreed-upon Work Product abbreviation, [version-id] is a
versioning identifier component composed of the single
character [Vv] (either case), followed by a numeric string
matching the rules for Version (e.g., V1.1), [stage-abbrev]
is a stage abbreviation in lower case characters, [revisionNumber]
is a two-digit number as prescribed below, and [ext] is a file
extension. Examples: emix-v1.0-csprd01.doc and xrd-v1.1-cs01.xml.
http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#filenameSyntax

[4] "Since the filename/frontpage matter is now responsibility
of the TC admin, we submitted the spec after it passed the TC
vote to the TC admin and asked for publication. I, as co-chair,
am partly responsible for the resulting messed up file name as
I forgot to make it very clear what we expected the filename
to be. I also failed to notice the filename when it did get
published. In any case, I think we need to look at fixing the
filenames to: sca-j-pojo-ci-testcases-1.1-wd09.<ext> ..."

-- 

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