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

 


Help: OASIS Mailing Lists Help | MarkMail Help

sca-c-cpp message

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


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



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