Software Configuration Management 1.0 Specification

Status: 1.0 Specification (in finalization)

This Version

• http://open-services.net/bin/view/Main/ScmSpecV1

• http://open-services.net/bin/view/Main/ScmSpecV1

• http://open-services.net/bin/view/Main/ScmSpecV1Original

• NickCrossley

• See the Contributors section below.

License

This work is licensed under a 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 RFC2119.

Table of Contents

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

Specification Versioning

See 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.
2. If version headers are returned and the client understands these versions, the client SHOULD process the data accordingly.
3. 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 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 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.

nested_prop       ::= link_property closure? "{" member_properties "}"
closure           ::= "*" | "!"
link_property     ::= property
member_properties ::= properties

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.

oslc_scm.context  ::= "oslc_scm.context=" uri_ref_esc

Example:

 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} 

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.

oslc_scm.delta ::= "oslc_scm.delta" | "oslc_scm.delta=" uri_ref_esc

Example:

 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 

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

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.

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 and Change Properties

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

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

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.
Example:

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

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 Properties

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

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.
Example:

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}

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.

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 Properties

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

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.
Example:

 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} 

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 Properties

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

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:

 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} 

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.

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 Properties

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

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.
Example:

 GET http://synergyserver:8888/oslc/file/1234?oslc.properties=dcterms:name,oslc_scm:status,oslc:creator

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 unified diff, and MAY support other representations.

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

Symlink Version Properties

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

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 unified diff, and MAY support other representations.

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 Resource Shapes as defined in the OSLC Core Specification

Service Provider Resource

OSLC SCM service providers MUST provide a Service Provider Resource that can be retrieved at a implementation dependent URI.

OSLC SCM service providers MAY provide a 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 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 core specification, but none are required by this specification.

Query Capabilities

There MUST be at least one Query Capability entry in the Services definition for an OSLC SCM provider.

SCM services MUST implement the 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 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)
• 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 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 Terms of Use. Details of the Covenant may be found 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.

References

• OSLC Core - OSLC Core Specification 2.0
• Dublin Core 1.1 - Dublin Core Metadata Element Set, Version 1.1
• FOAF - Friend of a Friend (FOAF) v0.98
• HTTP 1.1 - Hyper-text Transfer Protocol (HTTP/1.1)
• JSON - JavaScript Object Notation
• OAuth 1.0a - RFC5849 - The OAuth 1.0 Protocol
• RDF/XML Concepts - RDF/XML Concepts and Abstract Syntax
• RDF/XML Syntax - RDF / XML Syntax Specification (Revised)
• URI Syntax - URI Generic Syntax
• XML Namespaces - Namespaces in XML 1.0 (Third Edition)
• XSD Datatypes - XML Schema Part 2: Datatypes Second Edition