Software Configuration Management 1.0 Specification

*EARLY FORM OF V1.0 DRAFT SPECIFICATION*
See Scm Spec V1 for the current draft of this specification.

Introduction

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.

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.

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.

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.

For all resource types defined in this specification, all required properties (those defined with an occurrence of exactly-one or one-or-many) MUST exist for each resource and must be provided when requested. All other properties are optional, and might not exist on some or any resources; those that do not exist will not be present in the returned representation even if requested, while those that do exist MUST be provided if requested. Providers MAY define 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.

If no specific set of properties is requested, all properties are returned - both those defined in this specification as well as any provider-specific ones.

Consumer of OSLC SCM services should note that some resources may have a very large number of resources, and that some resources may be very large and/or expensive to compute. For this reason, consumers are strongly encouraged to use the oslc.properties parameter to limit the properties returned from a request 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 the 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=oslc_scm: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 MUST support the closure syntax with the oslc.properties parameter when used with oslc_scm.member as the link property, and MAY also support this closure syntax with other link properties and/or on the oslc.select query parameter.

OSLC SCM Resources

SCM services MUST accept well-formed GET and HEAD requests on the resources defined in this section, and MUST support use of the oslc.properties parameter on GET requests. SCM services MUST also support the closure of properties over links described in the next section. Some resources support additional parameters, as described below.

SCM services MAY fail to accept PUT, POST, 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 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 typically represent files and directories, but might also represent other resources such as requirements, models, assets, etc. An object version is an abstract type; most SCM resource types are subtypes of object version. Note that some of these subtypes might be restricted to having a single version of each object (resource).

Configuration

A container for a hierarchy of object versions. A configuration contains 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 contain 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 contents of a configuration is not frozen; the contents of and properties of the members might change, and the versions of the members might change. Configurations are object versions, but some providers might support only a single version of a configuration. With some providers, directories can contain symbolic links and configurations (sub-configurations) as well as files and subdirectories.

Baseline

A frozen configuration. If you look at the same baseline in the future, it will normally have the same contents (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. Baselines are object versions, but 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 object versions; they might be 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 an object versions that should be added to, replaced in, or removed from some configurations.

Directory version or file version

A kind of object version representing 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; note that no such resource type is used in SCM 1.0.

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 is 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 different containment relationships. The arrows from change sets represent the 'has associated changed objects' relationship; all other arrows represent an optional 'contains' relationship. Although these relationships might be many-to-many in the underlying provider, OSLC SCM 1.0 services only expose one to many relationships.

Object Version

An object version is a resource representing a specific version of an object that is being controlled in the SCM system. Objects typically represent files and directories, but might also represent other resources such as requirements, models, assets, etc. Other OSLC SCM resource types are typically specific types or subtypes of object version. An object version is an abstract type; most SCM resource types are subtypes of object version. Note that some of these subtypes might be restricted to having a single version of each object (resource). SCM services SHOULD NOT return any resource of type ObjectVersion from any operation.

Object Version Properties

An object version resource (and hence an object of most concrete SCM resource types) has the following properties:

Object Version Operations

Get

This operation gets information about the object version itself, and optionally information about its contents. Recursion down through containment relationships (such as a configuration/directory/file hierarchy) may be possible, depending on the provider and the type of object. Recursion through containment relationships may require provision of some containment context based on the URL, or explicitly supplied using an oslc_scm.context parameter. The operation is provided by a GET operation on some SCM resource, using the OSLC query syntax to determine the properties returned. Note that the resource(s) returned will be of specific subtypes; there are no actual resources of type ObjectVersion.
Example:

 GET http://synergyserver:8888/oslc/changeset/1234?oslc.properties=dcterms:name,dcterms:title,oslc_scm:status,oslc_scm:change{dcterms:title,dcterms:description} 

Change Set

A change set normally represents what should be indivisible unit of change in an SCM system: either all of the associated changed object versions should be applied to a configuration, or none. A change set might indicate object versions to be added to, replaced in, or removed from, a configuration. Simple version control systems may not provide change sets. For those that do, 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 changes; each change describes a single object version that has been added to, replaced in, or removed from, a configuration; the types of change may vary between providers. A change MAY be obtainable as a separate resource, or a provider MAY represent changes 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.

A change set is a type of object version, though many SCM services provide only a single version of a change set; a change may be a type of object version, but is not required to be.

Change Set and Change Properties

A change set has the following properties in addition to those of an object version:

A change has the following properties:

Change Set Operations

Get

This operation gets information about the change set itself, and optionally information about the changes (and indirectly the object versions) associated with this change set; no recursion through members (for example, directories) is provided. The operation is provided by a GET operation on a change set resource, using the OSLC query syntax to determine the properties returned, including the nested stream and change links. 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 will be 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}} 

Note that no operations on the oslc_scm:Change type are defined, since this is not required to be a gettable resource.

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, one can produce 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 are at liberty to supply such a property if appropriate.

A baseline is a type of object version.

Baseline Properties

A baseline has the following properties in addition to those of an object version:

Baseline Operations

Get

This operation gets information about the baseline itself, and optionally information about the resources associated with this baseline. Recursion down through the oslc_scm: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. The operation is provided by a GET operation on a baseline resource, using the OSLC query syntax to determine the properties returned, including the nested baselines, configurations, and change set links.
Example:

GET http://synergyserver:8888/oslc/baseline/2010-02-16_12:13:08_4532?
         oslc.properties=oslc_scm:changeset{dcterms:title,dcterms:description},
         oslc_scm:member!{dcterms:name,dcterms:title,oslc_scm:status}

Getchanges

return a representation of the difference between the given baseline and some provider-defined previous baseline, or a specific second baseline identified in an optional parameter. The operation is provided by a GET operation on a baseline resource, with the parameter oslc_scm.delta to find the delta between a baseline and the provider-defined previous baseline), or oslc_scm.delta=URL to find the delta between two baseline resources. In the latter case, it is an error if the URL specified in the oslc_scm.delta=URL parameter does not refer to a Baseline resource from the same SCM provider. By default, OSLC SCM providers MUST return a BaselineComparison as described below, and MAY support other representations.

Configuration

A configuration is a container for a hierarchy of object versions. A configuration contains 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 contain 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 contents of a configuration is not frozen; the contents of and properties of the members might change, and the versions of the members might change. Configurations are object versions, but some providers might support only a single version of a configuration. With some providers, directories can contain symbolic links and configurations (sub-configurations) as well as files and subdirectories.

A configuration is a type of object version.

Configuration Properties

A configuration has no properties in addition to those of an object version.

Configuration Operations

Get

This operation gets information about the configuration itself, and optionally information about the members of this configuration. Recursion down through the oslc_scm: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. The operation is provided by a GET operation on a configuration resource, using the OSLC query syntax to determine the properties returned, including the nested member links.
Example:

 GET http://synergyserver:8888/oslc/configuration/mainproject/17/7.2?oslc.properties=dcterms:name,dcterms:title,oslc_scm:status,oslc_scm:member*{dcterms:title,dcterms:description} 

Directory Version

A directory version is a type of object version. Note that a directory version resource refers to a specific version of a directory, for SCM systems that control versions of directories. A directory resource would represent the entire set of versions of some directory, but no OSLC SCM v1.0 operations return, or are provided on, directory resources.

Directory Version Properties

A directory version has the following properties in addition to those of an object version:

Directory Version Operations

Get

This operation gets information about the directory version itself, and optionally information about the members of this directory. Recursion down through the oslc_scm:member relationship (such as the directory/file hierarchy) MAY require that a configuration context is provided either in the URL path or using an oslc_scm.context parameter. If no context baseline or configuration is provided, the result MAY be just a set of oslc_scm:memberIdentifiers, not resources, in which case no recursion through directory members is possible. The operation is provided by a GET operation on a directory resource, using the OSLC query syntax to determine the properties returned, including the nested member links. 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,oslc_scm:member*{dcterms:name,oslc_scm:status} 

Getchanges

return a representation of the difference in membership between the given directory version and its immediate predecessor(s), or a second directory version identified in an optional parameter. In most cases, the two directory version resources would represent two different versions of the same directory. The operation is provided by a GET operation on a directory version resource, with the parameter oslc_scm.delta to find the delta between a directory version and its immediate predecessor(s), or oslc_scm.delta=URL to find the delta between two directory version resources. In the latter case, it is an error if the URL specified in the oslc_scm.delta=URL parameter does not refer to a DirectoryVersion resource from the same SCM provider. By default, OSLC SCM providers MUST return a DirectoryVersionComparison as described below, and MAY support other representations.

File Version

A file version is a type of object version. Note that a file version resource refers to a specific version of a file. A file resource would represent the entire set of versions of some file, but no OSLC SCM v1.0 operations return, or are provided on, file resources.

File Version Properties

A file version has the following properties in addition to those of an object version:

File Version Operations

Get

get information about the file version. The operation is provided by a GET operation on a file resource, using the OSLC query syntax to determine the properties returned. 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

Getchanges

return a representation of the difference in content between the given file version and its immediate predecessor(s), or a second file version identified in an optional parameter. In most cases, the two file version resources would represent two different versions of the same file. The operation is provided by a GET operation on a file version resource, with the parameter oslc_scm.delta to find the delta between a file version and its immediate predecessor(s), or oslc_scm.delta=URL to find the delta between two file version resources. In the latter case, it is an error if the URL specified in the oslc_scm.delta=URL parameter does not refer to a FileVersion resource from the same SCM provider. By default, the returned resource contains a unified diff; optionally, providers may allow additional query parameters to choose other diff formats.

Symlink Version

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

A symlink version is a type of object version.

Symlink Version Properties

A symlink version has the following properties in addition to those of an object version.

Symlink Version Operations

Get

get information about the symlink version, and optionally the contents of the target file or the members of the target directory. The operation is provided by a GET operation on a symlink version resource, using the OSLC query syntax to determine the properties returned.

Getchanges

return a representation of the difference between the target of the given symlink version and its immediate predecessor(s), or a second symlink version identified in an optional parameter. In most cases, the two symlink version resources would represent two different versions of the same symlink. The operation is provided by a GET operation on a symlink version resource, with the parameter oslc_scm.delta to find the delta between a symlink version and its immediate predecessor(s), or oslc_scm.delta=URL to find the delta between two symlink version resources. In the latter case, it is an error if the URL specified in the oslc_scm.delta=URL parameter does not refer to a SymlinkVersion resource from the same SCM provider. By default, the returned resource contains a unified diff; optionally, providers may allow additional query parameters to choose other diff formats.

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.

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 MUST support oslc.properties, oslc.prefix, oslc.where, and oslc.select parameters; note that usage of oslc.properties and oslc.prefix is not limited to queries. SCM services MAY also support oslc.searchTerms and oslc.orderBy.

In addition to the core OSLC query features, note that OSLC SCM providers MUST honor the closure syntax in the oslc.properties parameter as defined earlier

SCM providers MUST also honor the oslc_scm.context and oslc_scm.delta parameters defined on GET requests defined elsewhere in this specification, and MAY use those parameters in other requests.

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.

Notices and References

Authors and Contact Information

Authors of the OSLC SCM 1.0 Specification:

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

Please address all enquires to the OSLC SCM Lead, NickCrossley.

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.