Re: [oslc-ccm] Change sets review

["Nick Crossley" <ncrossley@us.ibm.com>]

Martin - thanks for the careful review. Comments below.

"Sarabura, Martin" ---03/11/2016 12:02:14 PM---Trunk version: https://tools.oasis-open.org/version-control/browse/wsvn/oslc-ccm/trunk/specs/config-

From: "Sarabura, Martin" <msarabura@ptc.com>
To: "OSLC CCM TC (oslc-ccm@lists.oasis-open.org)" <oslc-ccm@lists.oasis-open.org>
Date: 03/11/2016 12:02 PM
Subject: [oslc-ccm] Change sets review
Sent by: <oslc-ccm@lists.oasis-open.org>

---

Trunk version: https://tools.oasis-open.org/version-control/browse/wsvn/oslc-ccm/trunk/specs/config-mgt/config-resources.html

Csets version: https://tools.oasis-open.org/version-control/browse/wsvn/oslc-ccm/branches/cset/specs/config-mgt/config-resources.html#cset-shapes

 
Nick, I think that fundamentally this is fine. I have some issues/questions, below, but otherwise I think it's helpful conceptually and goes in a direction we'd want all tools to go some day.
 
 
Section 4
Header
- Servers MAY refuse to construct a basleine baseline of a baseline - What does this mean?
Nick: two typos - should have said "Servers MAY refuse to construct a baseline of a change set.

- For all purposes of version resolution, (the word all is not needed)
Nick: fixed.
 
Properties
- Is (reference: Dublin Core) the correct way to reference, or is that text in there provisionally?
Nick: Text copied from old property tables in some OSLC 2 specs - I do not think it adds any value, so I've removed all such text.

- dcterms:identifier - A unique identifier for this component change set.
Nick: fixed; this was in fact a shared property definition, so the fix is to say "A unique identifier for this resource."

- dcterms:modified - Each resource SHOULD have one instance of this property. Really? I should think that the most common scenario is a change set is created but not yet modified. Or is modified = created in that case?
Nick: fixed by removing that sentence.

- A type of configuration that accepts this configuration as a contribution. The hyperlink on accepts does not seem to be valid.
- A type of configuration that is acceptable as a contribution to this stream. Same thing - hyperlink wrong.
Nick: fixed.

- Accepts/Accepted By - Are these really valid? I should think once you've specified overrides you pretty much commit to a particular configuration and the change set can't be applied elsewhere. Of course maybe I don't really understand how these are supposed to be used.
Nick: The accepts & acceptedBy properties define what type of configurations you are allowed as contributions, or to what this config can contribute. For example, some systems might not want to expose all their internal configs (including possibly change sets, or some types of change set) directly as contributions to global configurations - they might have those internal config types as contributions to a top-level provider-specific config type, and have that top-level config type exposed as a legal contribution to a global config - and they mark this latter by including oslc_config:acceptedBy=oslc_config:configuration. So I think those 'acceptability' properties are orthogonal to whether or not a configuration is a change set.

- oslc_config:component - If the change set overrides a particular configuration, then shouldn't that configuration's component reference be sufficient? I'm thinking this property is redundant; maybe that's OK.
Nick: Yes, it probably is, but for efficient filtering in selection dialogs, etc., I think having the component property local is good.

- oslc:instanceShape - Once again, shouldn't this simply refer to the instance shape of the overridden configuration?
Nick: The shape of a change set is different, since it refers to the slightly different selections resource that has the optional 'Removals' and 'RemoveAll' types.

- I think you should add the term Selection to the Terminology section of the overview document. And change set, for that matter.
Nick: done, for Selections. Change set was already there.

I'm a visual learner and would benefit from having a diagram to illustrate how the terms apply - baseline, stream, configuration, etc. Do you have such a diagram? I can create one for you if you want. It would help me visualize all these concepts. Is there a tool that OASIS recommends for such diagrams?
Nick: A diagram would be very useful. I believe Jim has used some in Core, so we should check which tool or tools he used. I'd welcome any help you can provide here!
 
oslc_config:selects - Perhaps One-or-many? Well OK, maybe we should say in the Description that not having a selects value means this selection is a noop. Similarly for oslc_config:selections in the changeSet vocabulary.
Nick: zero selections is quite valid for global configurations that have only contributions and no selections.  Zero selects in a Selections resource is quite valid for one of type 'RemoveAll', for a change set that wants to add all selections explicitly, or even end up with an empty selections set.  Since the type can be RemoveAll for a change set, it is not a no-op. I think describing some of these special cases is an excellent topic for the primer.

oslc_config:selects Range - why not specify the valid values in the Range column rather than having a detailed description that lays out all the options?
Nick: not sure which part of the spec you are referencing here. The range of oslc_config:selects is 'any resource type', since the items in a configuration can be of any type.  For some of the other parts of the spec where there's a lot of explanatory text in the description column, it might be because we do not have ReSpec support for oslc:allowedValues.

Make sure you add Removals and RemoveAll to the vocabulary.
Nick: done.
 
That's all I have for now.
Best,
Martin