[oslc-scm] Responses to Frank's questions

[Nick Crossley]

Frank,

Thanks for the input, and sorry for the very long delay in responding - I 
wanted to get some of your questions and issues discussed by the workgroup 
in our meetings.

Below are my responses to all of your issues; the spec pages on the wiki 
have also been updated to reflect the current state.

> Remark 1:
> If we abstract files and directories into VersionedObjects, we must take 
into account that VersionedObjects could be any versioned entity, not only 
files and directories.
> We might even assert that a non-versioned object is a VersionedObject 
with only 1 version (ever). So we must be careful not to imply 
all-and-every object type under VersionedObjects.

We propose that all SCM resources are of types that are subtypes of 
versioned object, though providers may restrict some types to have only 
one version.  So, yes we do imply all-and-every object type under 
versioned object.

> Remark 2:
> The definition of Configuration will / may change into:
> Configuration - a thing that has a specific version of a one or more top 
level VersionedObject, and under those specific versions of any number of 
VersionedObjects.
> This sounds odd... If we abstract files and directories into 
VersionedObjects, we still must distinguish between 
CompositeVersionedObjects and AtomicVersionedObjects,
> where CompositeVersionedObjects are VersionedObjects that can contain 
(other?) VersionedObjects, and AtomicVersionedObjects cannot. This way, 
the configuration will become:
> Configuration - a thing that has a specific version of a one or more top 
level CompositeVersionedObject, and under those specific versions of any 
number of VersionedObjects.
> But why should a configuration be a (one or more) "directory" (or 
CompositeVersionedObject)? A configuration can also be one or more 
(individual) "files" (VersionedObjects)
> that "belong" together to a specific reason. For example, a 
configuration could be "all source files" or "build results of build 123" 
even when they are spread across multiple directories.

At least with the current set of SCM services, we see no need to 
distinguish between composite and atomic objects.  In fact, a specific 
type might be composite in one provider and atomic in another - consider a 
FileVersion, which might be a composite type in a Mac provider that kept 
data forks and resource forks separately.  Obviously, some types must be 
composite, such as configurations, baselines, directories, etc., but since 
we define specific operations on and properties of those types, we have no 
current need to define a common supertype.  This might change in the 
future as we add more resource types and operations on those types.

> Remark 3:
> I think that a definition with "a thing" is not accurate enough. I 
propose to call it a "collection" or a "set".
> And "one or more top level" is also to vague. What is "top level" and 
why do we need to distinguish between "zero" and "one or more"?
> Proposal: Configuration - a collection of a specific version of (a 
number of) CompositeVersionObjects.

The wording has been updated, and now allows for zero members.  We 
distinguish top-level members for the purpose of limiting the number of 
resources returned from queries, for scalability reasons.  By default, if 
you ask for the members of a container, you get only the immediate or 
top-level members; to get indirect members (members of members) you must 
use the oslc_scm:recurse parameter.

> Remark 3:
> I think we need the term "configuration" and "configuration item" 
because it is a commonly used term in SCM practice, even though the terms 
are often unclear or even undefined.
> A configuration may be considered identical to a 
CompositeVersionedObject (which results in a possibility of nested 
configurations) and a configuration item may be considered
> identical to a VersionedObject.

I have added a reference to the term "configuration item".

> Remark 4:
> Baseline - a frozen configuration. [...] a baseline can be an 
incremental baseline, with a link to some previous incremental or full 
baseline. 
> A baseline being incremental or full, linked to other baselines or not 
is an implementation choice of the provider. In all cases, it remains a 
frozen configuration,
> i.e. a reproducible, immutable configuration.

We agreed, and all reference to incremental baselines has now been 
removed.

> Remark 5:
> Component - an abstract concept representing some user-defined 
configuration or set of configurations
> I think a component should not be an "abstract" concept. It should be 
"an identifiable configuration".
> Moreover, I think that baseline and component are both identifiable 
configurations, uniquely named within the relevant namespace.

I'm still working on the distinction between configurations and components 
- I'll send you an update on that soon.

> Remark 6:
> In this sentence:
> required properties must be provided for any resource when requested; 
this does not imply that these properties are provided by default.
> I think this is contradictive. To me "must be provided" means the same 
as "are provided by default" (maybe it's my lack knowledge of English 
idiom). 

I've expanded the wording here to try to make the intent more clear.  A 
required property is one that every resource must have, and so the 
provider must return it if requested.  However, for scalability reasons, 
not all properties are returned by default, if no oslc:properties is 
given.  An optional property might not exist on all resources, and so 
might not be able to be provided even if requested.

> Remark 7:
> those that do not exist will not be present in the returned 
representation even if requested
> This should be extended with "those that do exist will be present in the 
returned representation if requested".

I added this.

> Remark 8: Change sets
> In the definition of change set, it is said to be "all or nothing". But 
how about objects (VersionedObjects) that are associated with multiple 
change sets? 
> ...
> In other words, we must be careful with statements like "all or 
nothing". I don't say that I disagree, only that we should be careful with 
it. 
> We should probably take a special look at "overlapping" change sets and 
how to deal with them.

I added some more wording to explain that an SCM system might not 
guarantee the atomicity of change sets.

> Remark 9: Change sets
> We should also be careful with a term like "one logical change".

I added wording to make it clear that "one logical change" is one possible 
use or intent of a change set, rather than a definition of a change set.

> Remark 10: olcs_scm:changes
> A change set is an identifiable set of versions. Therefore, 2 properties 
must be required: name and changes. The set of changes may be empty,
> but it should always be possible to request set set of versions.

Yes, it is always possible to request the set, and that set might be 
returned as an empty set, or the returned resource might just omit that 
property to indicate that the set is empty.  I've added wording to the 
spec to explain this.

> Remark 11: get change set
> Don't we need a set operation for a change set? Probably the property 
oslc_scm:changes is set as an indirect effect of another operation
> (e.g. check in, or submit). But other properties (e.g. owner) should be 
changeable.
> And we should be explicit about changing the name (dc:identifier) of a 
change set. I think we should forbid changing the dc:identifier property.

In OSLC SCM 1.0, there are no set or modify operations; the only 
operations defined are read-only GET requests.  This will certainly change 
in the future, and at that time we will need to define which properties 
may or may not be modified.

> Remark 12: Baseline of baselines
> The oslc_scm:baseline property should be defined differently. Whether a 
baseline is incremental or full is a matter of implementation by the 
provider. In both cases, the baseline is
> a complete configuration. So I would not waste a property on it.

Agreed - see earlier response: we have removed all references to 
incremental baselines.

> On the other hand, a baseline should be per definition (and the text may 
be adapted accordingly) a "previous" baseline + changes relative to the 
"previous" baseline
> In this case, the property oslc_scm:baseline specifies the previous 
baseline and the property oslc_scm:changesets specifies the changes 
relative to the previous baseline.

While this would be nice to provide, many (most?) SCM systems do not 
guarantee to keep available a complete historical record of the baseline 
of a baseline, etc.  Previous baselines might not be recorded, or they 
might be deleted, depending on the implementation.  For these reasons, we 
will not define an OSLC property for the 'previous baseline'.

> Remark 13: Baseline recursion
> This is something I don't understand. A baseline is a (frozen) 
configuration and a configuration is a set of VersionedObjects ...

As explained above, the recursion is provided as an option to retrieve the 
entire set of members in one GET operation.  It is an option because for 
scalability reasons you probably do not want that potentially very large 
list to be returned by default.  The recursion has nothing to do with 
creating the baseline, because we do not yet provide any such operation.

> Remark 14: Baseline get
> Don't we need more operations?

Yes, we need  baseline compare: I'll be adding that soon.

Again, thanks for your valuable feedback!

Nick.

 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://open-services.net/pipermail/oslc-scm_open-services.net/attachments/20100310/358c6963/attachment-0003.html>