ScmSpecV1 < Main

This wiki is locked. Future workgroup activity and specification development must take place at our new wiki. For more information, see this blog post about the new governance model and this post about changes to the website.
TWiki>
Main Web>ScmHome>ScmSpecV1 (11 May 2011, NickCrossley) (raw view)
<table cellspacing="1" cellpadding="5" border="0"> <tbody><tr><td valign="center"><img width="59" alt="OSLC_logo.png" src="%PUBURLPATH%/Main/OslcCoreSpecification/OSLC_logo.png" height="66" /></td><td valign="top">

---+!! Software Configuration Management 1.0 Specification
</td></tr> </tbody></table>

*Status:* 1.0 Specification (in finalization)

*This Version*
   * [[http://open-services.net/bin/view/Main/ScmSpecV1]]
*Latest Version* 
   * [[http://open-services.net/bin/view/Main/ScmSpecV1]]
*PreviousVersion* 
   * [[http://open-services.net/bin/view/Main/ScmSpecV1Original]]
*Author* 
   * NickCrossley
*Contributors* 
   * See the [[#Contributors][Contributors]] section below.

*License*

[[http://i.creativecommons.org/l/by/3.0/us/88x31.png]] <br /> This work is licensed under a [[http://creativecommons.org/licenses/by/3.0/us/][Creative Commons Attribution License]].

*Notation and Conventions*

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this document are to be interpreted as described in [[http://www.ietf.org/rfc/rfc2119.txt][RFC2119]].

*Table of Contents*

%TOC{depth="3"}%

---++ Introduction

_This section is informative._

Software Configuration Management covers a wide range of practices, including tracking and controlling changes in the software using version control, building software and creating baselines, reporting on the contents of such builds and baselines, establishing traceability from requirements and change requests to software revisions, etc. This specification defines a set of [[http://en.wikipedia.org/wiki/Representational_State_Transfer][RESTful]] interfaces using representations of resources, content types, the basic HTTP 1.1 methods and response codes. The capabilities of the interface definitions are driven by key integration scenarios and do not represent a complete set of operations on resources or resource types; service providers are neither required nor expected to expose their complete data model and application logic.

This version of the OSLC SCM specification describes services to browse the contents of baselines and change sets, and the version-controlled resources associated with those baselines and change sets. Clients may inspect the properties of these resources, and find differences between two such resources. No services are defined for the creation, modification, or deletion of resources.

---++ Base Requirements

---+++ Compliance

This specification is based on the [[OslcCoreSpecification][OSLC Core Specification 2.0]]. OSLC SCM 1.0 providers MUST be compliant with both the core specification 2.0 and this SCM 1.0 specification, and SHOULD follow all the guidelines and recommendations in both these specifications. As a result of following these requirements and recommendations, OSLC SCM 1.0 providers SHOULD also be compliant with the [[Reporting Specifications]].

The following table summarizes the requirements from OSLC Core Specification as well as some additional specific to SCM, qualifying some of the requirements from the OSLC Core Specification. See further sections in this specification or the OSLC Core Specification to get further details on each of these requirements.

| *Requirement* | *Level* | *Meaning* |
| Unknown properties and content | MAY / MUST | OSLC services MAY ignore unknown content and OSLC clients MUST preserve unknown content |
| Resource Operations | MUST | OSLC services MUST support resource operations via standard HTTP operations |
| Resource Paging | MAY | OSLC services MAY provide paging for resources but only when specifically requested by the client |
| Partial Resource Representations | SHOULD | OSLC services SHOULD support request for a subset of a resource's properties via the =oslc.properties= URL query string retrieval via HTTP GET |
| Service Provider Resources | SHOULD / MUST | OSLC service providers SHOULD provide at least one Service Provider Catalog and MUST provide a Service Provider resource for each service provider |
| Query Capabilities | MUST | OSLC service providers MUST provide query capabilities to enable clients to query for resources, via HTTP GET |
| Query Syntax | SHOULD / MAY | OSLC query capabilities SHOULD support the extended subset of the OSLC Core Query Syntax defined in this specification, and MAY use other query syntax |
| Delegated UI Dialogs | SHOULD | OSLC services SHOULD offer delegated UI selection dialogs specified via service provider resource |
| HTTP Basic Authentication | MAY | OSLC services MAY support Basic Auth, over http and/or https |
| OAuth Authentication | SHOULD / MAY | OSLC services SHOULD support OAuth and MAY indicate the required OAuth URLs via the service provider resource |
| Error Responses | SHOULD | OSLC services SHOULD provide error responses using Core defined error formats |
| RDF/XML Representations | MUST | OSLC services MUST provide an RDF/XML representation for responses to HTTP GET requests and queries requesting this representation. OSCL SCM service providers are not restricted to use of the constrained RDF/XML subset.  |
| JSON Representations | MUST | OSLC services MUST provide JSON representations that conform to the Core Guidelines for JSON in response to HTTP GET requests and queries requesting this representation. |
| Other Representations | MAY | OSLC services MAY provide other representations if requesting, such as HTML. |

---+++ Specification Versioning

See [[OslcCoreSpecification#Specification_Versioning][OSLC Core Specification Versioning section]].

OSLC SCM 1.0 Service providers MUST respond to all client requests with a representation that complies with this SCM 1.0 specification, including an =OSLC-Core-Version= header with a value of =2.0=, regardless of the version (if any) requested by the client.

Clients SHOULD provide at least the desired =OSLC-Core-Version= value in the headers of their requests, and SHOULD handle the returned versions as follows:
   1 If no version headers are provided in the response (the provider being non-compliant), the client MAY assume the requested version was returned, or MAY fail.
   1 If version headers are returned and the client understands these versions, the client SHOULD process the data accordingly.
   1 If version headers are returned, but the client does not understand these versions, the client MAY process any data it does understand, or MAY fail.

---+++ Namespaces

In addition to the namespace prefixes =oslc=, =rdf=, and =dcterms= described in the core specification, this specification uses a domain-specific namespace of =http://open-services.net/ns/scm#= with a default prefix of =oslc_scm=, and the RDF Schema namespace =http://www.w3.org/2000/01/rdf-schema#= with the prefix =rdfs=.

---+++ Resource Representations and Properties

SCM services MUST support both RDF/XML and JSON resource representations, and MAY support other representations. For RDF/XML representations, the returned content type MUST be =application/rdf+xml=; for JSON representations the content type MUST be =application/json=.

A normal GET request on any SCM resource MUST return the full base resource, with all the properties of that resource. These properties SHOULD include the properties defined in this specification, and MAY include additional provider-specific properties; providers SHOULD use their own namespaces for such properties, or use standard Dublin Core or RDF namespaces and properties where appropriate.

Clients may request derived resources with a subset of the base resource properties, using the [[OslcCoreSpecification#Selective_Property_Values][OSLC Core Specification =oslc.properties= syntax]]. Since some base resources may have a very large number of properties and some properties may be very large and/or expensive to compute, consumers are *strongly* encouraged to access derived resources, limiting the properties to the subset required.

---+++ Pagination

SCM services SHOULD support [[OslcCoreSpecification#Resource_Paging][paging]]; stable paging is not required.

---+++ Closure over links

The SCM data model is one with an arbitrarily nested structure. In order to allow consumers efficient access to hierarchic data such as a tree of directories and files in a baseline, SCM extends the OSLC Core definition of =oslc.properties= as follows.

<blockquote><verbatim>
nested_prop       ::= link_property closure? "{" member_properties "}"
closure           ::= "*" | "!"
link_property     ::= property
member_properties ::= properties
</verbatim></blockquote>

A nested property requested with the "*" closure option provides unlimited transitive closure over the named link property - so for example =oslc.properties=rdfs:member*{dcterms:name}= indicates that the members of the subject resource should be fetched, and the members of those members, recursively, until all members have been found, and that the =dcterms:name= property of the subject resource and of each of these members should be shown. Providers SHOULD detect cycles in the graph rather than failing or returning a never-ending response.

A nested property requested with the "!" closure option provides a potentially limited closure. The semantics are the same as for "*" except that the scope of the closure is limited and determined by the operation and the provider, as defined below.

SCM providers SHOULD support the closure syntax with the =oslc.properties= query string when used with =rdfs:member= as the link property, and MAY also support this closure syntax with other link properties and/or on the =oslc.select= query string.

---+++ Configuration Context

A single object in an SCM repository MAY be represented by more than one OSLC SCM resource - so the resources returned from two or more different URIs might represent the same underlying SCM object, and might have the same identity property. Two different OSLC SCM resources MAY represent the same SCM object seen in a specific context; in such cases, the two different resources MAY show different properties other than the identity property. For example, a single version of an SCM object representing a file system directory might have different members in different configuration contexts, in which case different resources would be used to represent the directory version in each context, and these multiple resources would have the same value for the =dcterms:identifer= property, but might have different =rdfs:member= properties.

The URI's returned as values for the member property of an SCM baseline or configuration SHOULD already imply that baseline or configuration as a context. For URI's obtained in other ways, a client can construct the URI for a resource representing the same underlying SCM object in some specific context by adding the =oslc_scm.context= query string and the context URI to the base URI. If the given object does not appear in that context, there is no such resource, and a GET would fail with the normal 404 error.

<blockquote><verbatim>
oslc_scm.context  ::= "oslc_scm.context=" uri_ref_esc
</verbatim></blockquote>

Example:
<blockquote><verbatim> GET http://synergyserver:8888/oslc/directory/src/17/7.2?oslc_scm.context=configuration/src/17/7.2&oslc.properties=dcterms:name,dcterms:title,oslc_scm:status,rdfs:member*{dcterms:name,oslc_scm:status} </verbatim></blockquote>

---+++ Resource Comparison

As defined later in this specification, a client can request the construction of a resource representing the difference between two other resources, by appending the =oslc_scm.delta= query string to the URI of the first resource to be compared; the second resource is identified either by an explicit URI in the =oslc_scm.delta= value, or implicitly by the provider if no URI value is given.

<blockquote><verbatim>
oslc_scm.delta ::= "oslc_scm.delta" | "oslc_scm.delta=" uri_ref_esc
</verbatim></blockquote>

Example:
<blockquote><verbatim> GET http://synergyserver:8888/oslc/baseline/2010-02-16_12:13:08_4532?oslc_scm.delta=oslc/baseline/2010-01-27_10:23:17_3891 </verbatim></blockquote>

---++ OSLC SCM Resources

SCM services MUST accept well-formed GET and HEAD requests on the resources defined in this section. On these requests, SCM services SHOULD support optional use of the [[OslcCoreSpecification#oslc_properties][oslc.properties]] query string, and the closure of properties over links, configuration context, and resource comparison URI search strings described in the previous section.

SCM services MUST support GET requests on the [[#Query_Capabilities][Query Capabilities]] resources defined later in this specification.

SCM services MAY fail to accept POST, PUT, and DELETE requests; if such requests are accepted, the semantics are not defined by this specification, but providers SHOULD map such requests to the logically equivalent create, update, and delete operations on SCM resources.

---+++ SCM Data Model

*Definition of terms*
   $ Object version: A resource representing a specific version of an object that is being controlled in the SCM system. In some SCM systems, this concept is called a configuration item. Objects frequently represent files and directories, but might also represent other resources such as requirements, models, assets, etc. Note that providers might restrict resources of some types to having a single version - for example, frequently change sets have only a single version, whereas files typically might have many versions.
   $ Configuration: A resource representing a set of object versions arranged in a hierarchy. A configuration has links to specific versions of any number of objects as immediate members forming the top level of the hierarchy. Each of those top-level objects versions may have links to any number of other object versions, with potentially a variety of containment relationships. For example, a configuration might contain a specific version of a file system directory object, and under that specific versions of any number of subdirectories and files.<br />The members of a configuration are defined as both the immediate top-level members and the members of those members, recursively, but excluding the members of any sub-configurations (members that are themselves configurations).<br />The contents of a configuration is not necessarily frozen; the contents of and properties of the members might change, and the versions of the members might change. Some providers might support only a single version of a configuration, other might support multiple versions of a configuration, with each version containing a different set of object versions, in a potentially different hierarchy. With some providers, directories can contain symbolic links and configurations (sub-configurations) as well as files and subdirectories. Providers may support other types of resources as members of a configuration, such as requirements, test cases, etc.
   $ Baseline: A frozen configuration. If you look at the same baseline in the future, it will normally have the same members (not all providers can guarantee complete immutability - for example, administrative actions might modify data). In some providers, baselines might be able to contain other baselines, while with other providers that might not be possible. Some providers might support only a single version of a baseline.
   $ Component: A configuration or set of configurations may be divided into components representing some user-defined set of object versions and/or sub-configurations; for example, components might be used to represent physical components or software modules. A provider is not required to implement components; they are used only as a way of limiting the scope of the closure over links. Components might or might not be resources; they might be dynamic sets of object versions chosen by other criteria such as property values. A provider can also treat each configuration and sub-configuration in a hierarchy as being separate components.
   $ Change set: A set of changes to be made to one or more configurations, where each change is described in terms of members (direct or indirect) that should be added to, replaced in, or removed from some configurations.
   $ Directory version or file version: A resource describing some specific version of a directory or file in the SCM system. Directories can contain files, subdirectories, and (in some providers) symbolic links and sub-configurations.
   $ Directory or file: A resource representing all versions of some particular directory or file.
   $ Symbolic link version: A kind of object version representing some specific version of a symbolic link, as used in UNIX file systems. A symbolic link holds a string property containing an absolute or relative file system path; this path might or might not point to a file system representation of some other SCM resource.

SCM services may restrict the set of members in a container in various ways. For example, the entries in one directory version may have to be unique. This specification does not define such restrictions, since they may not only vary between providers, but may also depend on the client or operating system used to view the configuration. For example, the names of files in a directory must be unique, but how uniqueness is determined varies between file systems: on UNIX, case is considered, while on Windows it is ignored, and on Mac OS X, files must be unique ignoring case using Unicode NFC.

The diagram below shows one possible data model using the above concepts, with directories and files as the objects in the SCM system. An SCM provider MAY allow other object types, with the same or different containment relationships; clients should not assume that any linked resource is an SCM object version or has some specific type (see [[OslcCoreSpecAppendixLinks#Don_t_make_assumptions_about_the][Oslc Core Links]]). The arrows from change sets represent the 'has associated changed objects' relationship; all other arrows represent the common =rdfs:member= relationship. Although these relationships might be many-to-many in the underlying provider, OSLC SCM 1.0 services only expose one to many relationships.

<img width="427" alt="OSLC_SCM_model.png" src="%ATTACHURLPATH%/OSLC_SCM_model.png" height="501" />

---+++ Common SCM Resource Properties

The following table shows properties that SHOULD be common to all SCM resources, unless otherwise specified for the resource types described below.

%TABLE{columnwidths="0,100,100,0,0,0"}%
| *Prefixed Name* | *Occurs* | *Value-type* | *Representation* | *Range* | *Description* |
| _OSLC Core properties_ ||||||
| dcterms:title | zero-or-one | XMLLiteral | n/a | n/a | Title (reference: Dublin Core) of the resource represented as rich text in XHTML content; this SHOULD include only content that is valid inside an XHTML &lt;span&gt; element. SCM providers SHOULD use this property for a human readable number, name, or synopsis of the object version. |
| dcterms:description | zero-or-one | XMLLiteral | n/a | n/a | Descriptive text (reference: Dublin Core) about resource represented as rich text in XHTML content; this SHOULD include only content that is valid and suitable inside an XHTML &lt;div&gt; element. SCM providers SHOULD use this property for a human-readable description of the object version, or a comment about the change in this version of the object. |
| dcterms:creator | zero-or-many | Resource | either | any | Creator or creators of resource (reference: Dublin Core). It is likely that the target resource is a [[OSLCCoreSpecAppendixA#foaf_Person_Resource][foaf:Person ]] but that is not necessarily the case. |
| dcterms:contributor | zero-or-many | Resource | either | any | Contributor or contributors to resource (reference: Dublin Core). SCM resources often use this to show the current owner - the entity responsible for this resource. It is likely that the target resource is a [[OSLCCoreSpecAppendixA#foaf_Person_Resource][foaf:Person ]] but that is not necessarily the case. |
| dcterms:created | zero-or-one | !DateTime | n/a | n/a | Timestamp of resource creation (reference: Dublin Core)  |
| dcterms:modified | zero-or-one | !DateTime | n/a | n/a | Timestamp of the latest resource modification (reference: Dublin Core) |
| rdf:type | one-or-many | Resource | reference | n/a | The resource type URI |
| oslc:instanceShape | zero-or-one | Resource | reference | [[OSLCCoreSpecAppendixA#oslc_ResourceShape_Resource][ =oslc:ResourceShape= ]] | Resource Shape that specifies allowed and required fields. All persistent SCM resources SHOULD have an instance shape. |
| oslc:serviceProvider | zero-or-one | Resource | reference | [[OslcCoreSpecification#Service_Provider_Resources][ =oslc:ServiceProvider= ]] | A link to the resource's OSLC Service Provider. |
| _SCM properties_ ||||||
| dcterms:identifier | zero-or-one | String | n/a | n/a | An internal identifier, possibly assigned by the SCM system. All persistent SCM resources SHOULD have an identifier, and this identifier MUST be unique amongst all currently existing object versions from this service provider. The string is not necessarily intended to be conveniently readable to humans. |
| dcterms:name | zero-or-one | String | n/a | n/a | A short name that is often used for an abbreviated identifier and used for presentation to end-users. |
| oslc_scm:fullName | zero-or-one | String | n/a | n/a | A full human-readable name of the object, unique amongst all current existing object versions from this service provider. |
| oslc_scm:status | zero-or-one | String | n/a | n/a | A string indicating the current status of the object version. |
| rdfs:member | zero-or-many | Resource | reference | any | A member resource that is a member of the the given container. Where the container resource is an SCM object version (such as a =Baseline=, =Configuration=, or =DirectoryVersion=), the member resource is also typically an SCM object version. Note this property may have multiple values, to show multiple members of the parent object. Different resources representing the same underlying directory version but as seen in different contexts may have different member property values. Note that this property identifies objects that are direct members of the parent object, as opposed to those that are members of members; indirectly included object versions may be returned as nested properties, possibly using the closure syntax. |

---+++ Change Set and Change

A change set is a unit of change in an SCM system. A change set might indicate object versions to be added to, replaced in, or removed from, a configuration. In most SCM systems, change sets are intended to be indivisible: either all of the associated changed object versions should be applied to a configuration, or none. Simple version control systems may not provide change sets. For SCM systems that do provide change sets, it is often impossible or an error to have a change set partially applied to a configuration. However, partially applied change sets are possible in many systems, due to manual intervention, conflicting dependencies, etc. Change sets have some properties of their own - for example, it is common to have an identifier for the change set, as well as some readable description of the purpose of the change. In some systems, a change set might be aggregated from several other change sets, perhaps representing a group of changes to be applied to some configuration.

Change sets often identify the modifications made for one logical change. For example, in languages such as C or C++, it would be common for a logical change to affect a header file that defines some API, and both the source file that implements the API and one or more source files where the API is used; a single change set can be associated with all these changes to ensure that they are applied as a unit.

In OSLC SCM, a change set contains zero or more Change resources; each Change describes a single object version that has been added to, replaced in, or removed from, a configuration; the exact nature of change may vary between providers. A Change MAY be obtainable as a separate resource, or a provider MAY represent Change resources purely as inlined properties of a change set.

Change sets may also be associated with specific stream or branches where that change is or should be applied.

Many SCM services provide only a single version of a change set.

| *Change Set Resource* ||
| Name | =ChangeSet= |
| Type URI | =http://open-services.net/ns/scm#ChangeSet= |

| *Change Type*  ||
| Name | =Change= |
| Type URI | =http://open-services.net/ns/scm#Change= |

---++++ Change Set and Change Properties

A change set has the following properties in addition to the common SCM properties:

%TABLE{columnwidths="0,100,100,0,0,0"}%
| *Prefixed Name* | *Occurs* | *Value-type* | *Representation* | *Range* | *Description* |
| oslc_scm:change | zero-or-many | Resource | either | [[#Change_Set_and_Change][ =oslc_scm:Change= ]] | Either a local [[#Change_Set_and_Change][ =oslc_scm:Change= ]] property, or a reference to a Change resource. Providers MAY choose not to represent changes as gettable resources, but instead always inline this property. |
| oslc_scm:stream | zero-or-many | Resource | reference | any | A reference to a resource defining the stream or branch to which this change set is or should be applied; this specification does not define the properties of a stream or branch resource. Note this property may have multiple values, to show multiple streams to which the change set might be applied. |

A change has the following properties, and need not have any of the common SCM properties:

%TABLE{columnwidths="0,100,100,0,0,0"}%
| *Prefixed Name* | *Occurs* | *Value-type* | *Representation* | *Range* | *Description* |
| oslc_scm:changeType | zero-or-many | String | n/a | n/a | A string representing the nature of the change. The value and meaning of this string varies between providers. Providers that do not distinguish different types of change may omit this property. |
| oslc_scm:changedObject | one-or-many | Resource | n/a | n/a | The object versions associated with this change; note there MUST be at least one such object version. Some SCM providers MAY represent rename operations by associating a change with two object versions; the =oslc_scm:changeType= string indicates this in some provider-specific manner. |

---++++ Change Set Methods

A client uses the normal http GET or HEAD methods to request information about a change set. From the returned information, or using the =oslc.properties= nested property syntax, the client may retrieve information about the changes associated with this change set, and also the object versions immediately associated with those changes. Since many SCM systems require a configuration context to determine the specific versions of members of directories, it might not be possible to use the closure syntax to recurse any further down a hierarchy from a change set through associated directory versions to file and subdirectory versions.

Note that a change set might not be associated with any object versions (perhaps because the change set is in the process of being set up, or because the associated changes were deleted), in which case the =oslc_scm:change= property is absent. <br /> Example:
<blockquote><verbatim> GET http://synergyserver:8888/oslc/changeset/1234?oslc.properties=dcterms:name,dcterms:title,oslc_scm:status,oslc_scm:change{oslc_scm:changeType,oslc_scm:changedObject{dcterms:title,dcterms:description}} </verbatim></blockquote>

Rersources of the =oslc_scm:Change= type MAY be represented only as inlined resources within change set resources, and hence might not have URIs.

---+++ Baseline

One purpose of an SCM system is to maintain collections of specific versions of objects - for example, the exact set of sources (and often the build artifacts as well) that were used to construct a specific version of your software, or the exact set of chapter document versions that were used in some version of a book. This hierarchy of specific versions of a set of objects is called a configuration. In many SCM systems, the versions of members of a configuration may vary over time, so at one moment a book contains version 1 of chapter 2, and a few days later the configuration is updated to contain version 2 of chapter 2. To reproduce an earlier state for testing, or for audit trail reasons, etc., it is often important to have a permanent record of the state of a configuration at some specific point in time. This frozen record of a configuration is called a baseline. Not all providers can guarantee complete immutability of baselines - for example, administrative actions might modify data. In some providers, baselines might be able to contain other baselines, while with other providers that might not be possible.

As just described, a baseline is or contains a configuration, so a baseline has links to a fixed hierarchy of specific object versions. In many SCM systems, a baseline is also associated with the change sets used to construct that baseline; these change sets normally represent the difference between this baseline and some previous baseline (which might or might not still exist). Since change sets are often linked to other OSLC resources such as change requests, and directly or indirectly to requirements, a client might be able to report on the defects fixed in a baseline, or the requirements satisfied in a baseline.

An SCM provider might use an earlier baseline during the development and construction of a newer baseline, but not all SCM systems keep track of such previous baselines thereafter; for this reason, no 'baseline baseline' property is defined in this specification, but providers MAY supply such a property if appropriate.

| *Baseline Resource* ||
| Name | =Baseline= |
| Type URI | =http://open-services.net/ns/scm#Baseline= |

---++++ Baseline Properties

A baseline has the following properties in addition to the common SCM properties:

%TABLE{columnwidths="0,100,100,0,0,0"}%
| *Prefixed Name* | *Occurs* | *Value-type* | *Representation* | *Range* | *Description* |
| oslc_scm:build | zero-or-many | Resource | reference | any | A reference to a resource defining a build; this specification does not define the properties of a build resource. |
| oslc_scm:stream | zero-or-one | Resource | reference | any | A reference to a resource defining the stream or branch in which this baseline was created; this specification does not define the properties of a stream or branch resource. |
| oslc_scm:subBaseline | zero-or-many | Resource | reference | any | A reference to a resource representing a sub-baseline contained in this baseline; note this property may have multiple values, to show multiple sub-baselines of the parent object. It is likely that the target resource is an [[#Baseline][ =oslc_scm:Baseline= ]] but that is not necessarily the case. |
| oslc_scm:changeSetAdded | zero-or-many | Resource | either | any | A reference to a resource representing a change set added in this baseline; note this property may have multiple values, to show multiple changesets added in the baseline. It is likely that the target resource is an [[#Change_Set_and_Change][ =oslc_scm:ChangeSet= ]] but that is not necessarily the case. |
| oslc_scm:changeSetModified | zero-or-many | Resource | either | any | A reference to a resource representing a change set modified in this baseline; note this property may have multiple values, to show multiple changesets modified in the baseline. It is likely that the target resource is an [[#Change_Set_and_Change][ =oslc_scm:ChangeSet= ]] but that is not necessarily the case. |
| oslc_scm:changeSetRemoved | zero-or-many | Resource | either | any | A reference to a resource representing a change set removed in this baseline; note this property may have multiple values, to show multiple changesets removed in the baseline. It is likely that the target resource is an [[#Change_Set_and_Change][ =oslc_scm:ChangeSet= ]] but that is not necessarily the case. |

---++++ Baseline Methods

A client uses the normal http GET or HEAD methods to request information about a baseline. From the returned information, or using the =oslc.properties= nested property syntax, the client may retrieve information about the members of this baseline and the change sets associated with it.. Recursion down through the =rdfs:member= relationship (such as a configuration/directory/file hierarchy) is possible using the closure syntax. Limited closure using the "!" closure operator may stop at a component boundary, as defined by the service provider.<br /> Example:
<blockquote><verbatim>GET http://synergyserver:8888/oslc/baseline/2010-02-16_12:13:08_4532?
         oslc.properties=oslc_scm:changeset{dcterms:title,dcterms:description},
         rdfs:member!{dcterms:name,dcterms:title,oslc_scm:status}</verbatim></blockquote>

---++++ Baseline Comparison

By adding the =oslc_scm.delta= query string to a baseline URI, a client can request a new resource representing the difference between the subject baseline and some other resource; the request MAY fail if the second resource is not also an SCM baseline.

If the optional URI value is provided, it provides the URI of the baseline that is to be compared with the subject baseline. If no URI is provided, the service provider determines an appropriate predecessor baseline . By default, OSLC SCM providers MUST return a =BaselineComparison= as described below, and MAY support other representations.

| *Baseline Comparison* ||
| Name | =BaselineComparison= |
| Type URI | =http://open-services.net/ns/scm#BaselineComparison= |

%TABLE{columnwidths="0,100,100,0,0,0"}%
| *Prefixed Name* | *Occurs* | *Value-type* | *Representation* | *Range* | *Description* |
| oslc_scm:baseline1 | exactly-one | Resource | reference | any | The resource used as the basis for the comparison; this is the provider-defined previous baseline by default, or the baseline specified in the =oslc_scm.delta= query string. This resource is likely to be a [[#Baseline][ =oslc_scm:Baseline= ]] but that is not necessarily the case. |
| oslc_scm:baseline2 | exactly-one | Resource | reference | any | The resource used as the target of the comparison; this is the baseline that was the self resource of the comparison request. This resource is likely to be a [[#Baseline][ =oslc_scm:Baseline= ]] but that is not necessarily the case. |
| oslc_scm:change | zero-or-many | Resource | either | any | A resource describing a single change between baselines, represented either inline or as a reference. Providers MAY choose not to represent changes as gettable resources, but instead always inline this property. This resource is likely to be a [[#Change_Set_and_Change][ =oslc_scm:Change= ]] resource, but that is not necessarily the case. |

A !BaselineComparison is only defined to have the properties listed above, and need not have any of the common SCM properties.

---+++ Configuration

As defined earlier, a configuration is a resource describing a set of object versions arranged into some hierarchy.

| *Configuration Resource* ||
| Name | =Configuration= |
| Type URI | =http://open-services.net/ns/scm#Configuration= |

---++++ Configuration Properties

A configuration has the following properties in addition to the common SCM properties:

%TABLE{columnwidths="0,100,100,0,0,0"}%
| *Prefixed Name* | *Occurs* | *Value-type* | *Representation* | *Range* | *Description* |
| oslc_scm:stream | zero-or-many | Resource | reference | any | A reference to a resource defining the stream or branch to which this configuration belongs; this specification does not define the properties of a stream or branch resource. Note this property may have multiple values, to show multiple streams to which the configuration might belong. |

---++++ Configuration Methods

A client uses the normal http GET or HEAD methods to request information about a configuration. From the returned information, or using the =oslc.properties= nested property syntax, the client may retrieve information information about the members of this configuration. Recursion down through the =rdfs:member= relationship (such as a configuration/directory/file hierarchy) is possible using the closure syntax. Limited closure using the "!" closure operator may stop at a component boundary, as defined by the service provider.<br /> Example:
<blockquote><verbatim> GET http://synergyserver:8888/oslc/configuration/mainproject/17/7.2?oslc.properties=dcterms:name,dcterms:title,oslc_scm:status,rdfs:member*{dcterms:title,dcterms:description} </verbatim></blockquote>

---+++ Directory, File, and Symlink Resources

SCM services MAY provide resources representing all versions of some specific object, such as a directory, a file, or a symbolic link; such resources would be of types =Directory=, =File=, and =Symlink=. Providers MAY also have versioned resources of other types. These resources SHOULD have the common SCM properties, and MAY have additional properties. A =DirectoryVersion= resource, as defined below, MAY contain references to resources representing all versions of its potential members.

---+++ Directory Version

A directory version resource refers to a specific version of a =Directory= resource, for SCM systems that control versions of directories.

| *Directory Version Resource* ||
| Name | =DirectoryVersion= |
| Type URI | =http://open-services.net/ns/scm#DirectoryVersion= |

---++++ Directory Version Properties

A directory version has the following properties in addition to the common SCM properties:

%TABLE{columnwidths="0,100,100,0,0,0"}%
| *Prefixed Name* | *Occurs* | *Value-type* | *Representation* | *Range* | *Description* |
| oslc_scm:memberIdentifier | zero-or-many | Resource | reference | any | A URI representing the identity of a member (file, directory, symbolic link, or configuration) of this directory version, but not necessarily the specific version of that member; this property may have multiple values, to show multiple members of the parent object. Typically, the URI is that of a resource representing all versions of some object, such as a =Directory=, =File=, or =Symlink= resource. A client can compare the =memberIdentifier= properties of two different directory versions to see which members were added or removed. |

---++++ Directory Version Methods

A client uses the normal http GET or HEAD methods to request information about a directory version. Recursion down through the =rdfs:member= relationship (such as a directory/file hierarchy) might be possible using the =oslc.properties= closure syntax; limited closure using the "!" closure operator may stop at a component boundary, as defined by the service provider. For some providers, this recursion MAY require that a configuration context is provided either in the URL path or using an =oslc_scm.context= query string. If no context baseline or configuration is provided, a directory version MAY have a number of =oslc_scm:memberIdentifier= properties and no =rdfs:member= properties, in which case no recursion through directory members is possible.

Example:
<blockquote><verbatim> GET http://synergyserver:8888/oslc/directory/src/17/7.2?oslc_scm.context=configuration/src/17/7.2&oslc.properties=dcterms:name,dcterms:title,oslc_scm:status,rdfs:member*{dcterms:name,oslc_scm:status} </verbatim></blockquote>

---++++ Directory Version Comparison

By adding the =oslc_scm.delta= query string to a directory version URI, a client can request a new resource representing the difference between the subject directory version and some other resource; the request MAY fail if the second resource is not also an SCM directory version.

If the optional URI value is provided, it provides the URI of the directory version that is to be compared with the subject directory version. If no URI is provided, the service provider determines an appropriate predecessor directory version (typically, the predecessor version of the same directory). By default, OSLC SCM providers MUST return a =DirectoryVersionComparison= as described below, and MAY support other representations.

| *Directory Version Comparison* ||
| Name | =DirectoryVersionComparison= |
| Type URI | =http://open-services.net/ns/scm#DirectoryVersionComparison= |

%TABLE{columnwidths="0,100,100,0,0,0"}%
| *Prefixed Name* | *Occurs* | *Value-type* | *Representation* | *Range* | *Description* |
| oslc_scm:directoryVersion1 | exactly-one | Resource | reference | any | The resource used as the basis for the comparison; this is the provider-defined previous directory version by default, or the directory version specified in the =oslc_scm.delta= query string. This resource is likely to be a [[#Directory_Version][ =oslc_scm:DirectoryVersion= ]] but that is not necessarily the case.  |
| oslc_scm:directoryVersion2 | exactly-one | Resource | reference | any | The resource used as the target of the comparison; this is the directory version that was the self resource of the comparison request. This resource is likely to be a [[#Directory_Version][ =oslc_scm:DirectoryVersion= ]] but that is not necessarily the case. |
| oslc_scm:memberAdded | zero-or-many | Resource | reference | any | A URI representing the identity of a member (file, directory, symbolic link, or configuration) added to this directory version, but not necessarily the specific version of that member. Typically, the URI is that of a resource representing all versions of some object, such as a =Directory=, =File=, or =Symlink= resource, just as in the =memberIdentifier= property of a =DirectoryVersion=. |
| oslc_scm:memberRemoved | zero-or-many | Resource | reference | any | A URI representing the identity of a member (file, directory, symbolic link, or configuration) removed from this directory version, but not necessarily the specific version of that member. Typically, the URI is that of a resource representing all versions of some object, such as a =Directory=, =File=, or =Symlink= resource, just as in the =memberIdentifier= property of a =DirectoryVersion=. |

A !DirectoryVersionComparison is only defined to have the properties listed above, and need not have any of the common SCM properties.

---+++ File Version

A file version resource refers to a specific version of a =File= resource.

| *File Version Resource* ||
| Name | =FileVersion= |
| Type URI | =http://open-services.net/ns/scm#FileVersion= |

---++++ File Version Properties

A file version has the following properties in addition to the common SCM properties:

%TABLE{columnwidths="0,100,100,0,0,0"}%
| *Prefixed Name* | *Occurs* | *Value-type* | *Representation* | *Range* | *Description* |
| oslc_scm:content | exactly-one | Resource | reference | any | A reference to the byte contents of the file version. |
| oslc_scm:mimeType | zero-or-one | String | n/a | n/a | The MIME type of the file version content. |

---++++ File Version Methods

A client uses the normal http GET or HEAD methods to request information about a file version. The file content may be retrieved using the link in the =oslc_scm:content= property. <br /> Example:
<blockquote><verbatim> GET http://synergyserver:8888/oslc/file/1234?oslc.properties=dcterms:name,oslc_scm:status,oslc:creator</verbatim></blockquote>

---++++ File Version Comparison

By adding the =oslc_scm.delta= query string to a file version URI, a client can request a new resource representing the difference between the subject file version and some other resource; the request MAY fail if the second resource is not also an SCM file version.

If the optional URI value is provided, it provides the URI of the file version that is to be compared with the subject file version. If no URI is provided, the service provider determines an appropriate predecessor file version (typically, the predecessor version of the same file). By default, OSLC SCM providers MUST return a =FileVersionComparison= as described below, containing a [[http://en.wikipedia.org/wiki/Diff#Unified_format][unified diff]], and MAY support other representations.

| *File Version Comparison* ||
| Name | =FileVersionComparison= |
| Type URI | =http://open-services.net/ns/scm#FileVersionComparison= |

%TABLE{columnwidths="0,100,100,0,0,0"}%
| *Prefixed Name* | *Occurs* | *Value-type* | *Representation* | *Range* | *Description* |
| oslc_scm:fileVersion1 | exactly-one | Resource | reference | any | The resource used as the basis for the comparison; this is the provider-defined previous file version by default, or the file version specified in the =oslc_scm.delta= query string. This resource is likely to be a [[#File_Version][ =oslc_scm:FileVersion= ]] but that is not necessarily the case.  |
| oslc_scm:fileVersion2 | exactly-one | Resource | reference | any | The resource used as the target of the comparison; this is the file version that was the self resource of the comparison request. This resource is likely to be a [[#File_Version][ =oslc_scm:FileVersion= ]] but that is not necessarily the case. |
| oslc_scm:unifiedDiff | exactly-one | String | n/a | n/a | The unified diff between the contents of the two file versions, describing the changes made from =fileVersion1= to =fileVersion2=. |

A !FileVersionComparison is only defined to have the properties listed above, and need not have any of the common SCM properties.

---+++ Symlink Version

A symlink version resource refers to a specific version of a =Symlink= resource.

Some SCM systems have direct support for symbolic links, as provided on UNIX file systems. Service providers that support symbolic links MUST use the !SymlinkVersion resource type for such a specific version of such an object. Note that service providers that do support symbolic links MAY return resources of this type to clients running on systems that do not support symbolic links; for example, a UNIX provider can return =SymlinkVersion= resources to a client running on Windows.

SCM 1.0 does not define a resource type for links to other SCM resources, as opposed to symbolic links whose target is a file system paths; if a provider needs to represent links to other SCM resources, a separate resource type MUST be defined (using a resource shape in the Query Capability and/or Creation Factory).

| *SymlinkVersion Resource* ||
| Name | =SymlinkVersion= |
| Type URI | =http://open-services.net/ns/scm#SymlinkVersion= |

---++++ Symlink Version Properties

A symlink version has the following properties in addition to the common SCM properties.

%TABLE{columnwidths="0,100,100,0,0,0"}%
| *Prefixed Name* | *Occurs* | *Value-type* | *Representation* | *Range* | *Description* |
| oslc_scm:target | exactly-one | String | n/a | n/a | The target of the symbolic link, as a string containing a relative or absolute file system path. |

---++++ Symlink Version Methods

A client uses the normal http GET or HEAD methods to request information about a symlink version.

---++++ Symlink Version Comparison

By adding the =oslc_scm.delta= query string to a symlink version URI, a client can request a new resource representing the difference between the subject symlink version and some other resource; the request MAY fail if the second resource is not also an SCM symlink version.

If the optional URI value is provided, it provides the URI of the symlink version that is to be compared with the subject symlink version. If no URI is provided, the service provider determines an appropriate predecessor symlink version (typically, the predecessor version of the same symlink). By default, OSLC SCM providers MUST return a =SymlinkVersionComparison= as described below, containing a [[http://en.wikipedia.org/wiki/Diff#Unified_format][unified diff]], and MAY support other representations.

| *Symlink Version Comparison* ||
| Name | =SymlinkVersionComparison= |
| Type URI | =http://open-services.net/ns/scm#SymlinkVersionComparison= |

%TABLE{columnwidths="0,100,100,0,0,0"}%
| *Prefixed Name* | *Occurs* | *Value-type* | *Representation* | *Range* | *Description* |
| oslc_scm:symlinkVersion1 | exactly-one | Resource | reference | any | The resource used as the basis for the comparison; this is the provider-defined previous symlink version by default, or the symlink version specified in the =oslc_scm.delta= query string. This resource is likely to be a [[#Symlink_Version][ =oslc_scm:SymlinkVersion= ]] but that is not necessarily the case. |
| oslc_scm:symlinkVersion2 | exactly-one | Resource | reference | any | The resource used as the target of the comparison; this is the symlink version that was the self resource of the comparison request. This resource is likely to be a [[#Symlink_Version][ =oslc_scm:SymlinkVersion= ]] but that is not necessarily the case. |
| oslc_scm:unifiedDiff | exactly-one | String | n/a | n/a | The unified diff between the targets of the two symlink versions, describing the changes made from =symlinkVersion1= to =symlinkVersion2=. |

A !SymlinkVersionComparison is only defined to have the properties listed above, and need not have any of the common SCM properties.

---++ OSLC SCM Service Provider Capabilities

---+++ Resource Shapes

OSLC SCM services providers MUST support [[OslcCoreSpecification#Resource_Shapes][Resource Shapes]] as defined in the [[OslcCoreSpecification#Resource_Shapes][OSLC Core Specification]]

---+++ Service Provider Resource

OSLC SCM service providers MUST provide a [[OslcCoreSpecification#Service_Provider_Resources][Service Provider Resource]] that can be retrieved at a implementation dependent URI.

OSLC SCM service providers MAY provide a [[OslcCoreSpecification#Service_Provider_Catalog_Resources][Service Provider Catalog Resource]] that can be retrieved at a implementation dependent URI.

OSLC SCM service providers MUST provide a =oslc:serviceProvider= property for their defined resources that is the URI to a [[OslcCoreSpecification#Service_Provider_Resources][Service Provider Resource]].

OSLC SCM service providers MUST supply a value of =http://open-services.net/ns/scm#= for the property =oslc:domain= on either =oslc:Service= or =oslc:ServiceProviderCatalog= resources.

---+++ Creation Factories

SCM providers MAY define creation factories compliant with the [[OslcCoreSpecification#Creation_Factories][core specification]], but none are required by this specification.

---+++ Query Capabilities

There MUST be at least one [[OslcCoreSpecification#Query_Capabilities][Query Capability]] entry in the Services definition for an OSLC SCM provider.

SCM services MUST implement the [[OSLCCoreSpecQuery][OSLC Core Query Syntax]], and SHOULD support =oslc.properties=, =oslc.prefix=, =oslc.where=, and =oslc.select= query string; note that usage of =oslc.properties= and =oslc.prefix= is not limited to queries. SCM services MAY also support =oslc.searchTerms= and =oslc.orderBy=.

SCM services MUST support queries for baselines and change sets, and SHOULD support queries for any resource types.

---+++ Delegated User Interface Dialogs

_See [[OslcCoreSpecification#Delegated_User_Interface_Dialogs][Delegated UIs]]._

SCM services SHOULD provide a picker (selection dialog) for baselines and one for change sets. Services MAY provide other selection dialogs.

SCM providers MAY define also define delegated creation dialogs, but none are required by this specification.

---++ Appendix A: Examples

_This appendix is informative._

TBD.

---++ Appendix B: Resource Shapes

_This appendix is informative._

TBD.

---++ Appendix C: Notices and References

_This appendix is informative._

---+++ Contributors

   * NickCrossley (IBM; OSLC SCM Lead)
   * JohnCamelon (IBM)
   * GeoffreyClemm (IBM)
   * JimConallen (IBM)
   * [[RobinF][Robin Fuller]] (IBM)
   * PeterHack (IBM)
   * PaulKomar (IBM)
   * ToddLainhart (IBM)
   * JeanMichelLemieux (IBM)
   * SamitMehta (IBM)
   * EricMinick (!UrbanCode)
   * FrankSchophuizen (TOPIC Embedded Systems)
   * EricSink (!SourceGear)
   * JasonSmith (IBM)

---+++ Reporting Issues on the Specification

The working group participants who author and maintain this specification monitor a distribution list where issues or questions can be raised, see [[http://open-services.net/mailman/listinfo/oslc-scm_open-services.net][Oslc-Scm Mailing List]]

Also the issues found with this specification and their resolution can be found at ScmSpecIssuesV1.

---+++ Intellectual Property Covenant

The members of the Working Group (or as appropriate, their employers) have documented a Patent Non-Assertion Covenant for implementations of the SCM 1.0 Specification, as described in the open-services.net [[http://open-services.net/html/Terms.html][Terms of Use]]. Details of the Covenant may be found [[ScmSpecificationCovenantV1][here]].

---+++ Supporting Documents

These non-normative documents do not form part of the specification, but provide examples and references, and document the use cases, design decisions, and rationale that led to the OSLC SCM 1.0 specification. In any discrepancy between what is described in these documents and the actual specifications, the specification prevails.

| *Document* | _TBD: Temporary comments - remove before finalization_ |
| [[ScmDrillDownStory][Drill Down Story]] | Frozen for SCM 1.0 |
| [[ScmTerminology][SCM Terminology]] | Out of date - needs work |

---+++ References

   * OSLC Core - [[OslcCoreSpecification][OSLC Core Specification 2.0]]
   * Dublin Core 1.1 - [[http://dublincore.org/documents/2010/10/11/dces/][Dublin Core Metadata Element Set, Version 1.1]]
   * FOAF - [[http://xmlns.com/foaf/spec/20100809.html][Friend of a Friend (FOAF) v0.98]]
   * HTTP 1.1 - [[http://tools.ietf.org/html/rfc2616][Hyper-text Transfer Protocol (HTTP/1.1)]]
   * JSON - [[http://json.org/][JavaScript Object Notation]]
   * OAuth 1.0a - [[http://tools.ietf.org/html/rfc5849][RFC5849 - The OAuth 1.0 Protocol]]
   * RDF/XML Concepts - [[http://www.w3.org/TR/2004/REC-rdf-concepts-20040210/][RDF/XML Concepts and Abstract Syntax]]
   * RDF/XML Syntax - [[http://www.w3.org/TR/2004/REC-rdf-syntax-grammar-20040210/][RDF / XML Syntax Specification (Revised)]]
   * URI Syntax - [[http://tools.ietf.org/html/rfc3986][URI Generic Syntax]]
   * XML Namespaces - [[http://www.w3.org/TR/REC-xml-names/][Namespaces in XML 1.0 (Third Edition)]]
   * XSD Datatypes - [[http://www.w3.org/TR/xmlschema-2][XML Schema Part 2: Datatypes Second Edition]]
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
png	OSLC_SCM_model.png	manage	19.8 K	12 Apr 2010 - 10:59	NickCrossley	SCM data model example
Topic revision: r39 - 11 May 2011 - 14:06:51 - NickCrossley
Main
Webs
Main
Sandbox
TWiki
Copyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use
Ideas, requests, problems regarding this site? Send feedback