Re: [oslc-core] OSLC Core 3.0 overview is ready for TC review

["Jim Amsden" <jamsden@us.ibm.com>]

Martin, 
Thanks for the great review - comments
below. I'll try to have a new version today. I also forgot to add the section
on resource formats.


Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575




From:      
 Martin P Pain <martinpain@uk.ibm.com>
To:      
 Jim Amsden/Raleigh/IBM@IBMUS
Cc:      
 "OASIS OSLC Core
TC Discussion List (oslc-core@lists.oasis-open.org)" <oslc-core@lists.oasis-open.org>
Date:      
 07/23/2015 06:51 AM
Subject:    
   Re: [oslc-core]
OSLC Core 3.0 overview is ready for TC review
Sent by:    
   <oslc-core@lists.oasis-open.org>

---

I've just looked at the latest diff,
not done a top-to-bottom read. Mostly editorial issues, with some comments
on the changed content too: 
1.        There's
now an empty <section> element with ID "conformance". Is
that something that we need to flesh out?
<jra>That section
is boilerplate filled in by ReSpec. The section with id conformance is
a marker for where the section goes.</jra>

2.        In
"Version Compatibility": "There is a significant number
of existing OSLC domains" should that be "are"? Perhaps
"There exist a significant number of OSLC domains" would be better,
or "A significant number of OSLC domains exist" or "have
been defined". Very minor point, but it made me trip when reading
it. "A significant number of OSLC domains, client implementations
and server implementations already exist".
<jra> are is
good (depends on what is the noun a significant number, or existing domains).
I took you suggestion.<;jra>
 
3.        "it's
compatibility needs" -> "its compatibility needs"
<jra>Done</jra>

4.        "there
is no need for OSLC Core 3.0 to require servers or clients to utilize an
OSLC-Core-Version header with a value of 3.0". This sentence doesn't
provide the context for understanding why we're mentioning the OSLC-Core-Version
header. Would a link to the definition of the header in 2.0 help to set
the picture? Even if it's something the implementors don't need to know
about, at least they can understand what it is that we're saying that they
don't need to use, and why we have to say that. e.g. the link could say
"as previously used in the OSLC 2.0 compatibility guidance".
I see we already have the link later, but it doesn't explicitly give the
context for the OSLC-Core-Version header.

<jra>I added some context: "Existing OSLC 2.0 clients and servers use the OSLC-Core-Version header described in <a href="">http://open-services.net/bin/view/Main/OslcCoreSpecification#Specification_Versioning">OSLC Core 2.0 Specification Versioning</a> to indicate what OSLC version they expect or support. But exposing version numbers..."</jra>

5.        Should we explicitly allow OSLC-Core-Version: 3.0? I suggest not. Servers that support pre-Core (1.0) and 2.0 need to receive OSLC-Core-Version: 2.0 in order to return a 2.0 representation. It doesn't look like we ever say that clients SHOULD provide that header, (it says "We expect clients that target the Core to send this HTTP header.").
<jra>Agreed</jra>

3.0 clients with 1.0 & 2.0 servers: So if you have a server that supports 1.0 and 2.0 (so requires the header in requests from a 2.0 client), and the client is upgraded to support OSLC 3.0, then it needs to still send OSLC-Core-Version: 2.0, otherwise that server will fall back to the 1.0 resources, which are not compatible. If we care about new 3.0-only clients being compatible with 2.0 serves, then either we should "expect that" clients send, or clients MUST send, "OSLC-Core-Version: 2.0" (despite being 3.0 clients).
<jra>We didn't discuss 3.0 Client compatibility with 2.0 or 1.0 servers, but any 3.0 client that is aware of the 2.0 subset of 3.0 should be able to use it directly. They would be expected to provide the header if they want to be sure to avoid getting a 1.0 response. That's already documented for 2.0 servers so I didn't repeat it.</jra>

2.0 clients with 3.0 servers: However I think we said that the compatibility requirement is that 2.0 clients work with 3.0-only servers. In which case 3.0 clients only need to send the "OSLC-Core-Version: 2.0" header if they need to be compatible with older servers (we could still make it a SHOULD). 3.0-only servers can ignore the header. If a server initially supported 2.0 but was then upgraded to 3.0, I suggest we explicitly say that on receiving an "OSLC-Core-Version: 2.0" header it returns the 3.0 representation. This is counter-intuitive, but we have no need to request 2.0 representations from a 3.0 server as they are 100% backwards compatible. (At least in core - other domains can define their own ways of specifying version if they need it).
<jra>Agreed. But this essentially means the OSLC-Core-Version header is meaningless to a 3.0 server since it returns the same thing whether the header is there or now. So it needn't be mentioned. That is, if we're going to move away from version control couples in specifications, we should do that, not add a lot of unnecessary "clarifying" special cases.

I don't think the existing statement saying to support compatibility with 1.0 refer to the 2.0 spec is enough, as clients not wanting to be compatible with 1.0 can break compatibility with 2.0 servers that also implement 1.0 if the client doesn't send "OSLC-Core-Version: 2.0".
<jra>Clients that access 2.0 servers are: 1) OSLC 1.0 clients - they get 1.0 responses by default from 2.0 servers and don't interoperate with 3.0 servers (that's intentional). 2) OSLC 2.0 clients - they already know how to interact with 2.0 servers that may or may not implement 1.0 by using the OSLC-Core-Version header. 3) OSLC 3.0 Clients - if they are accessing 2.0 servers that might return 1.0 responses without the header, then they would have to provide the header as specified in the Core 2.0 Specification Versioning section. I can add this statement.

6.        " that is compatible with 2.0 The response may include" - missing full stop after "2.0". - DONE.

Kind regards,

Martin Pain
Software Developer - Green Hat
Rational Test Virtualization Server, Rational Test Control Panel

Phone:+44 (0)1962 815317 | Tie-Line:37245317 E-mail: martinpain@uk.ibm.com Find me on:  and within IBM on:

IBM United Kingdom Limited Registered in England and Wales with number 741598 Registered office: PO Box 41, North Harbour, Portsmouth, Hants. PO6 3AU



From:        "Jim Amsden" <jamsden@us.ibm.com>
To:        "OASIS OSLC Core TC Discussion List (oslc-core@lists.oasis-open.org)" <oslc-core@lists.oasis-open.org>
Date:        22/07/2015 22:09
Subject:        [oslc-core] OSLC Core 3.0 overview is ready for TC review
Sent by:        <oslc-core@lists.oasis-open.org>

---

See https://tools.oasis-open.org/version-control/browse/wsvn/oslc-core/jra-editing/specs/oslc-core.html. This has the initial set of changes required to address OSLC2 compatibility.


Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575


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