Re: [sca-j] Filename for POJO testcase PR doc

[Mike Edwards <mike_edwards@uk.ibm.com>]

Robin,

I appreciate the desire for the use
of directories and I am sure we can adopt them.

However, I fail to see how directories
have anything to do with the name of a single file, and
in particular why this name has been
chosen:

sca-j-pojo-ci-1.1-testcases-1.0-csprd01.pdf

- in this case, our concern is the "1.0"
that has been added in a filename that already contains a "1.1"

- 1.1 in this file concerns a particular
level of the specifications - adding a "1.0" tag seems to confuse
things a lot.

- why is the "1.0" tag required??


Yours, Mike

Dr Mike Edwards		Mail Point 146, Hursley Park
STSM		Winchester, Hants SO21 2JN
SCA & Services Standards		United Kingdom
Co-Chair OASIS SCA Assembly TC
IBM Software Group
Phone:	+44-1962 818014
Mobile:	+44-7802-467431 (274097)
e-mail:	mike_edwards@uk.ibm.com

From:	Robin Cover <robin@oasis-open.org>
To:	Anish Karmarkar <Anish.Karmarkar@oracle.com>
Cc:	OASIS Java <sca-j@lists.oasis-open.org>
Date:	02/02/2011 16:16
Subject:	Re: [sca-j] Filename for POJO testcase PR doc

---

Anish,

I spotted your message just in passing, about filenames
and the Naming Directives.

I would encourage you and others on the TC to consider
making changes to the sca-j publication tree for
the existing and new specifications so as to conform
(more) with the Naming Directives.  What I'm writing here
would apply to all OASIS TCs.

Obviously, for work already underway, the naming practices
should be transitioned carefully so that nothing breaks.

On the other hand, I think there's strong motivation to
move toward the use of directories rather than storing
everything the TC produces in one huge directory.  Have
a look please:

http://docs.oasis-open.org/opencsa/sca-j/?D=D

In preparation for publication of the new Naming Directives,
Staff and TAB did a lot more work to set out rational
principles for use of directories, so that OASIS TCs don't
end up with multiple dozens or hundreds of files
(for different specifications) in one massive directory.
The earlier Naming Guidelines (2006-2008 vintage) [1]
also recommended the use of directories (paths) for
resources, but in the new Naming Directives, the
rule was made clearer:

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]

The Naming Directives don't recognize all of the issues
arising from legacy naming practices, or the need for
reasonable extensions/exceptions to accommodate work
"parts", and so forth.  But the core principles are clear
I hope: use directories, and in particular, a separate
directory for each new release (i.e., each publication instance
or event corresponding to a TC spec approval) per
"/[stage-abbrev][revisionNumber]/" above csd01, csd02...

It takes some planning to design the use of a directory
for a Work Product and potentially for parts of
a Work Product, but the rewards are great for usability
(end users) and for resource management.  Without
directories, it becomes difficult to manage resources
through collections of URI aliases. When one uses
directories (just like I imagine most of us do on
local computers), it's easy to store everything relating
to each new release (csd01, csd02, pr01, cds03, pr02,
cs01, cs02...) in one place.  Access and URI management
are much improved.

Please let me know how I can help you in this goal, with
respect to the OASIS Library and the new Naming
Directives.

  - Robin

[1] old Naming Guidelines, no longer current
http://docs.oasis-open.org/specGuidelines/namingGuidelines/metadata.html#specURIs

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 Wed, 2 Feb 2011, Anish Karmarkar wrote:

> I recently noticed that the POJO testcase PR doc is named
> sca-j-pojo-ci-1.1-testcases-1.0-csprd01.pdf [1]
>
> Why is there a "1.0" in there?
>
> The syntax for filenames per the naming directives [2] is:
> [WP-abbrev]-[version-id]-[stage-abbrev][revisionNumber].[ext]
>
> The filename should therefore be:
> sca-j-pojo-ci-testcases-1.1-csprd01.pdf
>
> -Anish
> --
>
>
> [1] 
> http://docs.oasis-open.org/opencsa/sca-j/sca-j-pojo-ci-1.1-testcases-1.0-csprd01.pdf
> [2] http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html
>
> ---------------------------------------------------------------------
> 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
>

---------------------------------------------------------------------
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