[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [sca-j] Re: Code Artifact Links and Layout.
Fair enough. I'm going to start a new email thread for the proposal. Stay tuned. Dave Booz STSM, BPM and SCA Architecture Co-Chair OASIS SCA-Policy TC and SCA-J TC "Distributed objects first, then world hunger" Poughkeepsie, NY (845)-435-6093 or 8-295-6093 e-mail:booz@us.ibm.com |------------> | From: | |------------> >--------------------------------------------------------------------------------------------------------------------------------------------------| |Mary McRae <mary.mcrae@oasis-open.org> | >--------------------------------------------------------------------------------------------------------------------------------------------------| |------------> | To: | |------------> >--------------------------------------------------------------------------------------------------------------------------------------------------| |David Booz/Poughkeepsie/IBM@IBMUS | >--------------------------------------------------------------------------------------------------------------------------------------------------| |------------> | Cc: | |------------> >--------------------------------------------------------------------------------------------------------------------------------------------------| |Jeff Mischkinsky <jeff.mischkinsky@oracle.com>, Mike Edwards <mike_edwards@uk.ibm.com>, sca-c-cpp@lists.oasis-open.org, "OASIS Java" | |<sca-j@lists.oasis-open.org>, Bryan Aupperle/Raleigh/IBM@IBMUS | >--------------------------------------------------------------------------------------------------------------------------------------------------| |------------> | Date: | |------------> >--------------------------------------------------------------------------------------------------------------------------------------------------| |02/26/2010 09:50 AM | >--------------------------------------------------------------------------------------------------------------------------------------------------| |------------> | Subject: | |------------> >--------------------------------------------------------------------------------------------------------------------------------------------------| |Re: [sca-j] Re: Code Artifact Links and Layout. | >--------------------------------------------------------------------------------------------------------------------------------------------------| Hi David, 1. Give me a proposal :) Tell me what you want the section named and where it will be placed: a. add a URI following each doc/html/pdf set, b. add a new section immediately following URIs, or c. add a new section immediately preceding related work. 2. Whatever namespace is on the cover of the SCA-J spec. Mary On Feb 26, 2010, at 9:40 AM, David Booz wrote: > Mary, > > Placing links on the cover page of the CAA specification is no problem. > Where to place them is a problem. Is it ok if we add a new section on the > cover page? The Assembly test suite documents use the "Related Work" > section, but that doesn't seem appropriate since these code artifacts are > normative along with the spec. The only section close to what we want is > the Declared XML Namespace section, but that doesn't work because we're not > talking about XML namespaces. > > WRT your second point, the SCA-J specifications do not have their own > namespace and therefore don't have their own namespace document, they share > the namespace document with the Assembly TC. Is that the namespace > document that you were referring to? If so, then we're in agreement with > you on this point. > > > Bryan, I added you because I think my email will bounce off the cpp list. > > Dave Booz > STSM, BPM and SCA Architecture > Co-Chair OASIS SCA-Policy TC and SCA-J TC > "Distributed objects first, then world hunger" > Poughkeepsie, NY (845)-435-6093 or 8-295-6093 > e-mail:booz@us.ibm.com > > > |------------> > | From: | > |------------> >> --------------------------------------------------------------------------------------------------------------------------------------------------| > |Mary McRae <mary.mcrae@oasis-open.org> | >> --------------------------------------------------------------------------------------------------------------------------------------------------| > |------------> > | To: | > |------------> >> --------------------------------------------------------------------------------------------------------------------------------------------------| > |Mike Edwards <mike_edwards@uk.ibm.com> | >> --------------------------------------------------------------------------------------------------------------------------------------------------| > |------------> > | Cc: | > |------------> >> --------------------------------------------------------------------------------------------------------------------------------------------------| > |Jeff Mischkinsky <jeff.mischkinsky@oracle.com>, sca-c-cpp@lists.oasis-open.org, "OASIS Java" <sca-j@lists.oasis-open.org> | >> --------------------------------------------------------------------------------------------------------------------------------------------------| > |------------> > | Date: | > |------------> >> --------------------------------------------------------------------------------------------------------------------------------------------------| > |02/24/2010 08:56 AM | >> --------------------------------------------------------------------------------------------------------------------------------------------------| > |------------> > | Subject: | > |------------> >> --------------------------------------------------------------------------------------------------------------------------------------------------| > |[sca-j] Re: Code Artifact Links and Layout. | >> --------------------------------------------------------------------------------------------------------------------------------------------------| > > > > > > Following the Assembly Test Suite, my recommendation is to: > > 1) Place links on the cover page > 2) Include in the namespace document (since they are a resource and part of > the specification, just like any schema or wsdl files. > > Mary > > > > On Feb 24, 2010, at 4:43 AM, Mike Edwards wrote: > > > Mary, > > I think you may have misunderstood my email. > > My email was about the Test Suite, not the main Assembly > specification. > > I am pointing out that the Assembly Test Suite, which does have a > specification document of its own, is a precedent for the handing > of a specification document that has associated code artifacts. > > In the case of the Java and C++ SCA specifications, the main > specification itself has code artifacts - and I am suggesting > that these code artifacts are treated by those specifications in the > same way that the code artifacts are treated by the > test suite specification. These artifacts are NOT test suite > artifacts and are described already in the body of the specification > itself so that there is no justification or need to create a separate > specification document which describes them. > > Thus, I propose that for the SCA Java CAA specification: > > 1) Links are placed on the frontmatter of the CAA specification which > point to the locations of the code artifacts > > 2) The code artifacts consist of: > - the Binary JAR file > - the Source ZIP file > - the source files in expanded directory layout > - the Javadoc files > > all these artifacts should be loaded to the OASIS site and be > available publicly as specification artifacts. > > > Yours, Mike. > > Strategist - Emerging Technologies, SCA & SDO. > Co Chair OASIS SCA Assembly TC. > IBM Hursley Park, Mail Point 146, Winchester, SO21 2JN, Great > Britain. > Phone & FAX: +44-1962-818014 Mobile: +44-7802-467431 > Email: mike_edwards@uk.ibm.com > > > Fro Mary McRae <mary.mcrae@oasis-open.org> > m: > > To: Mike Edwards/UK/IBM@IBMGB > > > Cc: Bryan Aupperle <aupperle@us.ibm.com>, Jeff Mischkinsky < > jeff.mischkinsky@oracle.com>, sca-c-cpp@lists.oasis-open.org, "OASIS > Java" <sca-j@lists.oasis-open.org> > > Dat 23/02/2010 15:55 > e: > > Sub Re: Code Artifact Links and Layout. > jec > t: > > > > > > > > Hi Mike, > > I don't think that's accurate. > > The SCA Assembly specification is here: > http://docs.oasis-open.org/opencsa/sca-assembly/sca-assembly-1.1-spec.html > > > It makes no mention of the test cases on the cover page. > > What they did - and what I think the other TCs should do as well - is > to create a separate document that describes the testcases: > http://docs.oasis-open.org/opencsa/sca-assembly/sca-assembly-1.1-testcases-cd01.html > > > They are also identified in the namespace document: > http://docs.oasis-open.org/ns/opencsa/scatests/2009032 > > I'd like to see the other TCs do the same and follow SCA Assembly's > lead. > > Mary > > > > On Feb 23, 2010, at 5:07 AM, Mike Edwards wrote: > > > Mary, > > There is some precedence for dealing with code artifacts related to > OASIS TC specifications. > > As a first point, I think that in general all the artifacts are > indeed described somewhere in the specification document(s) under > consideration. The main consideration is that in general code > artifacts are organized into packages, somewhat analogous to > namespaces for XML documents, but that the conventions and formalisms > for code artifacts do differ from those that apply to > XML artifacts. For example, there is nothing quite equivalent to the > namespace URL and there is as a result no obvious location > at which you would expect to find a given code artifact. > > So, to take Java code as a particular case. Java code is organised > into packages - and packages do imply a relative directory > hierarchy which directly reflects the package naming. So, to take an > example from the OASIS SCA-J TC, there is the ComponentContext > interface, which is in the "org.oasisopen.sca" package. This implies > a directory structure like this: > > org > - oasisopen > - sca > > with the file ComponentContext.java contained in the "sca" directory > (along with a group of other files that are in the SCA-J API) > > However, in this case, the "org" directory can then be placed into > some arbitrary other directory at the choice of the publisher. > In the OASIS SVN repository, it is placed into a directory > src/main/java, following conventions used by build systems including > Maven > and Eclipse. > > The binary code files (ie compiled form) for these source code files > are organized similarly, but in Java, they are organized into JAR > files, which are basically ZIP files with a specific form of > Manifest. Within the ZIP file, the relative directory structure is > preserved. Thus, > all the files in the Java CAA specification are compiled into the > file sca-caa-apis-1.1-CD04.jar (for example) and inside that jar > file, > the directory structure org/oasisopen/sca appears, containing > ComponentContext.class (amongst others). > > So, the question at issue is where the various artifacts get > published on the OASIS system. > > > > The precedence I'd like to look at concern the SCA Assembly Test > Suite. > > This is a formal specification document, published here: > http://docs.oasis-open.org/opencsa/sca-assembly/sca-assembly-1.1-testcases-cd01.pdf > > > This Test Suite has a pile of associated artifacts - XML files of > various forms and also code artifacts including Java and C++ code > files. > The artifacts are available in a ZIP file, which has a reference > under the "Related Work" item on the frontmatter: > http://docs.oasis-open.org/opencsa/sca-assembly/sca-assembly-1.1-testcases-cd01.zip > > > I note that the same set of artifacts are available in an "unpacked" > form at the following address: > http://docs.oasis-open.org/opencsa/sca-assembly/sca-assembly-1.1-testcases-cd01/ > > - however this address is not mentioned in the frontmatter of the > specification document (it probably should be). > > The test suite artifacts are then described in various places > throughout the document. > > Now "Related Work" may not be the best possible location for the > links to these artifacts, although it seems OK to me. > Perhaps the right place in many ways is similar to "Declared XML > Namespaces" but perhaps should be called > "Declared Code Artifacts" or some such - certainly for Java, the use > of a given Java package name is important - it > must not clash with other code in exactly the same way that XML > namespaces must not clash. However, a Java package > name is not an XML namespace. > > > So - shall we simply follow the convention used by the SCA Assembly > Test Suite or do you want to organize it differently? > > Yours, Mike. > > Strategist - Emerging Technologies, SCA & SDO. > Co Chair OASIS SCA Assembly TC. > IBM Hursley Park, Mail Point 146, Winchester, SO21 2JN, Great > Britain. > Phone & FAX: +44-1962-818014 Mobile: +44-7802-467431 > Email: mike_edwards@uk.ibm.com > > From: Mary McRae <mary.mcrae@oasis-open.org> > > > To: Bryan Aupperle <aupperle@us.ibm.com> > > Cc: Jeff Mischkinsky <jeff.mischkinsky@oracle.com>, > sca-c-cpp@lists.oasis-open.org > > Date: 22/02/2010 17:58 > > > Subje Re: [sca-c-cpp] Public Review of SCA Client and Implementation > ct: Model for C and C++ Specifications - 15 day review > > > > > > > > > Seems like they should be included as a Normative Reference, listed > as an artifact in the namespace document, noted on the cover page of > the spec ... something. Without an explicit reference how would > anyone know where to find them? > > I'm happy to work with a team of representatives from each TC or the > liaisons subcommittee to work out something that will be applied > consistently across all of the TCs. > > The next question would be if that code is authoritative, what > standing does it have within the TC? Shouldn't there be a document > that describes the artifacts and that document, along with the > artifacts themselves, voted and approved at each stage? Submitted for > public review? > > Mary > > > > On Feb 22, 2010, at 12:37 PM, Bryan Aupperle wrote: > > > They are not explicitly referenced by name or URI, but there is a > statement in the conformance section stating that there are source > code artifacts and that they are authoritative over the spec text > relative to the API definition. > > If necessary, it would be reasonable to have them put in a zip and > have a link in some appropriate place in the specification. > > I know the Java TC is discussing essentially the same concern. > > 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: Mary McRae <mary.mcrae@oasis-open.org> > > > To: Bryan Aupperle/Raleigh/IBM@IBMUS > > Cc: sca-c-cpp@lists.oasis-open.org, Jeff Mischkinsky < > jeff.mischkinsky@oracle.com> > > Date: 02/20/2010 04:10 PM > > > Subje Re: [sca-c-cpp] Public Review of SCA Client and Implementation > ct: Model for C and C++ Specifications - 15 day review > > > > > > > > > Thanks Bryan. > > Sorry, but more questions. Are they actually referenced in the > specification somewhere or noted in the namespace document? If not, > is there some other document that will be describing them/referencing > them? How is someone to know that they exist or should be used? Are > they part of the specification or some ancillary support material > with no official standing within the TC? > > I have no objections to uploading them per se, but if they aren't > part of the specification and not referenced anywhere it doesn't make > much sense. > > Mary > > > > On Feb 18, 2010, at 2:10 PM, Bryan Aupperle wrote: > > > It is a file in C or C++ that is used to define an API. A header > file normally has an extension of .h and is used when compiling a > program. I.e. a machine readable version of an API definition. > > 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: Mary McRae <mary.mcrae@oasis-open.org> > > > To: Bryan Aupperle/Raleigh/IBM@IBMUS > > Cc: sca-c-cpp@lists.oasis-open.org > > Date: 02/18/2010 01:49 PM > > > Subje Re: [sca-c-cpp] Public Review of SCA Client and Implementation > ct: Model for C and C++ Specifications - 15 day review > > > > > > > > > > I'm going to now ask a stupid question (sorry!): What's a header > file? > > Mary > > > > On Feb 18, 2010, at 1:31 PM, Bryan Aupperle wrote: > > > The zip packages we sent for this PR included some header files. If > I look at http://docs.oasis-open.org/opencsa/sca-c-cpp/ I do not see > any of the header files. What do we need to do to get the header > files published? > > Thanks. > > 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: Mary McRae <mary.mcrae@oasis-open.org> > > > To: members@lists.oasis-open.org, tc-announce@lists.oasis-open.org > > Cc: OASIS TAB <tab@lists.oasis-open.org>, > sca-c-cpp@lists.oasis-open.org > > Date: 02/14/2010 10:53 PM > > > Subje [sca-c-cpp] Public Review of SCA Client and Implementation Model > ct: for C and C++ Specifications - 15 day review > > > > > > > > > > > To OASIS members, Public Announce Lists: > > The OASIS Service Component Architecture / C and C++ (SCA-C-C++) TC > has recently approved the following specifications as a Committee > Draft and approved them for public review: > > Service Component Architecture Client and Implementation Model for C + > + Specification Version 1.1 > Service Component Architecture Client and Implementation Model for C > Specification Version 1.1 > > The public review starts today, 15 February 2010, and ends 2 March > 2010. This specification was previously submitted for a 60-day public > review on 24 April 2009[1]; this 15-day review is limited in scope to > changes made from the previous review. All changes are marked. > > This is an open invitation to comment. We strongly encourage feedback > from potential users, developers and others, whether OASIS members or > not, for the sake of improving the interoperability and quality of > OASIS work. > > More non-normative information about the specification and the > technical committee may be found at the public home page of the TC > at: > http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=sca-c-cpp . > Comments may be submitted to the TC by any person through the use of > the OASIS TC Comment Facility which can be located via the button > marked "Send A Comment" at the top of that page, or directly at: > http://www.oasis-open.org/committees/comments/index.php?wg_abbrev=sca-c-cpp > . > > Submitted comments (for this work as well as other works of that TC) > are publicly archived and can be viewed at: > http://lists.oasis-open.org/archives/sca-c-cpp-comment/. All comments > submitted to OASIS are subject to the OASIS Feedback License, which > ensures that the feedback you provide carries the same obligations at > least as the obligations of the TC members. > > The specification documents and related files are available here: > > Service Component Architecture Client and Implementation Model for C + > + Specification Version 1.1 > Editable Source: > http://docs.oasis-open.org/opencsa/sca-c-cpp/sca-cppcni-1.1-spec-cd03.doc > > PDF: > http://docs.oasis-open.org/opencsa/sca-c-cpp/sca-cppcni-1.1-spec-cd03.pdf > > HTML: > http://docs.oasis-open.org/opencsa/sca-c-cpp/sca-cppcni-1.1-spec-cd03.html > > Namespaces: > http://docs.oasis-open.org/ns/opencsa/sca/200903 > http://docs.oasis-open.org/ns/opencsa/sca-c-cpp/cpp/200901 > > Service Component Architecture Client and Implementation Model for C > Specification Version 1.1 > Editable Source: > http://docs.oasis-open.org/opencsa/sca-c-cpp/sca-ccni-1.1-spec-cd04.doc > > PDF: > http://docs.oasis-open.org/opencsa/sca-c-cpp/sca-ccni-1.1-spec-cd04.pdf > > HTML: > http://docs.oasis-open.org/opencsa/sca-c-cpp/sca-ccni-1.1-spec-cd04.html > > Namespaces: > http://docs.oasis-open.org/ns/opencsa/sca/200903 > http://docs.oasis-open.org/ns/opencsa/sca-c-cpp/cpp/200901 > > > OASIS and the SCA-C-C++ TC welcome your comments. > > > Mary P McRae > Director, Standards Development > Technical Committee Administrator > OASIS: Advancing open standards for the information society > email: mary.mcrae@oasis-open.org > web: www.oasis-open.org > twitter: @fiberartisan #oasisopen > phone: 1.603.232.9090 > > [1] > http://lists.oasis-open.org/archives/tc-announce/200904/msg00011.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 > > > > > > > > > > > > > > > > > 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 > > > > > > > > > > > > > > > > --------------------------------------------------------------------- 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]