Baselines
Introduction
This page describes the concept of a baseline of a set of resources. To paraphrase the
OSLC SCM specification:
Often, systems need to maintain collections of resources - for example, the set of sources that were used to construct your software, or the set of requirements that apply to a specific model of a product. This set of resources, their states, and the links between them, is called a configuration. During the development and evolution of a system, the set of resources in a configuration and the states of those resources may vary. To reproduce an earlier state for testing, or for audit trail reasons, etc., it is often important to have a permanent and immutable record of a configuration at some specific point in time. This immutable record of a configuration is called a baseline. Not all providers can guarantee complete immutability of baselines - for example, administrative actions might modify data.
A baseline captures the exact state of a set of resources, including the state of each resource in the set and the links between them. An immutable record of a resource could be made through copying, versioning, or a change in the state of the original resource.
Use Cases
Create a baseline
As a software developer, I need to record the exact state of my SCM configuration for building a library that will be used by other software components, including the right header files, the binary build artifacts for various platforms, the README or release notes, etc.
As a requirements manager, I need to record the exact state of my fighter jet requirements following a review by the Air Force. Since requirements may change, I need this snapshot to be available at any time later, so we can review what the Air Force has or has not yet approved. Links between my requirements must be included in the snapshot.
As a user of a system, I need to treat a thing (resource, metric, etc.) or collection of things as a related group, and I want the system to record and/or freeze a copy at some point in time, or (for resources that are versioned in some way by their provider) record the version of the resource at that time. The state of links between resources must also be captured.
Modify and delete baselines
As a release manager, I need to make a formal release of a software product. The previously created baseline for the tested final build of the product should be marked and preserved, adding appropriate version numbers and comments to the updated baseline. After that, I want to delete several previous test and published baselines for earlier intermediate states of this new product release, and the associated intermediate versions of build artifacts, in order to save space and speed up future queries.
As a baseline manager, I need to be able to modify the properties of a baseline, and link that baseline to other resources such as test results.
As a baseline manager, I need to be able to delete or mark obsolete old and unused baselines, so they do not affect users’ operations and queries.
Control the use of a baseline, component-based development
As a software developer, I need to be able to mark my new library baseline as available to the testing group, but I do not yet want the new library to be picked up by other software developers unless they explicitly choose to do so. Once the library has passed testing, we need to be able to mark the baseline as suitable for general use
As a user of a system, I need to announce and/or control the availability of a collection of resources to some audience (such as a testing group, or another development group using component assembly, etc.)
As the process owner, I need to be able to set rules for when new baselines or new versions of baselines are picked up by the users of my system
As a user of baselines, I need to be able to decide which baseline or version of a baseline to use as a sub-component, library, or similar dependency (possibly within limits and policies determined by the process owner)
Compare baselines
As a test engineer, I want to be able to see the new change sets included in a baseline wrt the baseline I tested last week, and I want to be able to trace those change sets back to any associated defects or requirement changes.
As a creator or user of baselines, I need to be able to compare two baselines, or the current state of the system vs. a baseline, and get a report of the differences, tracking those differences back to their root causes across multiple SCM domains
Baseline Definitions
What is a baseline?
- A baseline is an OSLC gettable resource
- It has certain properties of its own
What is in a baseline?
- A baseline has a collection of versions and/or states of resources that are members of the baseline
- The members of a baseline may themselves have member resources that are also part of the baseline, forming a linked graph of resources (perhaps a hierarchy)
- Baseline members are gettable resources, so may have their own unique properties and links, and other resources may link to baseline members
- Baseline members may also have links to resources outside the baseline: such referenced resources might not be immutable
- Baseline member resources need not all be from the same OSLC domain (or indeed from any OSLC domain)
Types of baseline
- A baseline might be a member of a larger baseline
- The term ‘composite baseline’ has been used to describe a baseline whose members come from multiple OSLC domains; since the proposals on this page address baselines whose members may come from one or more OSLC domains and providers, they include 'composite baselines'; that term is considered redundant
- Similarly, this proposal also covers baselines some of whose members are not OSLC or RDF resources.
Immutability
Baselines themselves are, in general, mutable resources: they may have a mutable set of local properties such as comments, status, etc., and possibly a mutable set of link properties such as associated test results, etc.
Baselines are intended to provide an immutable view of their members. How such a view is maintained depends on the provider – some systems might provide read-only copies or versions of the member resources, some might record enough of the state of the member resource to present an immutable view of mutable resources. In general, a system cannot promise complete immutability of the view or the underlying resources.
The set of members of a baseline is normally immutable. However, a large cross-domain baseline might need to be constructed over time using multiple tools manager by multiple owners. It is quite possible that those owners are not necessarily all available at the same time - one might be out on vacation or sick at the time someone else needs to start creating the composite baseline. Hence the member set needs to be able to be mutable and have members added to it incrementally until it is marked as complete.
Once a baseline has been completely constructed and its properties set as desired, it should be possible to get an immutable view of the baseline resource itself, as well as its members.
Durability
Some baselines may be more important than others - for example, the product release or regulatory inspection baseline might need to be very complete and kept for a very long time, whereas an interim baseline formed to tell the testing group that some version and/or part of a product is ready for test might be transitory and incomplete.
OSLC Baseline Proposal
This proposal defines a very simple but general baselining capability. There are two concepts: a
camera capability for finding or making immutable snapshots, copies, or versions of resources, and a
Baseline resource that holds links to members of a baseline. The camera capability manipulates resources from a single OSLC provider; the baseline capability allows arbitrary resources to be members of a baseline, including non-OSLC and non-RDF resources.
The Camera Capability
An OSLC service provider MAY provide a camera capability, to form or discover immutable snapshots, copies, or versions of its resources. This capability is indicated by the presence of a
camera property on the service provider resource, giving the URI of the camera, as well as information about the camera's features.
Additional property on
oslc:ServiceProvider
resource:
Prefixed Name |
Occurs |
Value-type |
Representation |
Range |
Description |
oslc:camera |
zero-or-one |
Resource |
Either |
oslc:Camera |
The camera capability for this service provider. A GET on this resource returns the camera properties described below; a POST on this resource is a request to perform a snapshot of one or more resources. |
The
oslc:Camera
resource has the following properties:
Prefixed Name |
Occurs |
Value-type |
Representation |
Range |
Description |
oslc:snapshotMember |
zero-or-one |
String |
n/a |
n/a |
The name of the member property in the result of a snapshot request for multiple resources (see below). |
oslc:dependentMember |
zero-or-many |
String |
n/a |
n/a |
The name of a property that links a resource to a dependent resource (see below). |
Camera Usage and Results
- A consumer requests an immutable snapshot of one or more resources belonging to a single service provider by a POST to the camera URI, with the POST data containing the URI of the resources for which a snapshot is requested. The result is the URI of an immutable resource. If the POST request was given only a single resource to snapshot, the result might be a new version or copy of that resource, or it might be the original resource made immutable. If multiple resources were passed to the snapshot request, the result would be a container resource with the snapshot resources linked using the camera's
oslc:snapshotMember
property, or using rdfs:member
if no oslc:snapshotMember
property was defined.
- Each resource in the set returned from a snapshot request has the same properties as the original resource except for member links as described below, and the optional addition of the
oslc:readOnly
state predicate set to true
.
- When a snapshot of a resource is taken, a snapshot MUST also be taken of all resources that are from the same service provider as the initial resource and that are the object of any of the camera's
oslc:dependentMember
properties; in the immutable resource returned from the snapshot request, the dependent member properties MUST point to the (possibly newly created) immutable member resource snapshots.
- The resources returned from a snapshot request, including any dependent member resources SHOULD be immutable; a PUT on any of these resources SHOULD fail.
Finding Existing Snapshots
From Steve:
Does there need to be a way for a client to discover the snapshots that exist? For example, does a client always need to create/get a snapshot or can it pick from existing ones? If we feel there is a need for discovery of existing snapshots, then we could add snapshots as a property of the camera - the camera remembers what snapshots it has taken. A client can then find all snapshots with a GET on the camera URI. The snapshots for a given resource could be found if we added an
oslc:snapshotOf
property to a snapshot.
An alternative design could be using a collection pattern for creating and finding snapshots of each individual resource, like this:
- Create a snapshot using POST uri?oslc.snapshot
- Get all snapshots associated with resource with GET uri?oslc.snapshot
However, this approach does not provide information on the existence of the camera capability or its properties.
OSLC Baseline Resource
This baseline resource is adapted from the
OSLC SCM baseline, for a more general usage across OSLC:
Prefixed Name |
Occurs |
Value-type |
Representation |
Range |
Description |
Dublin Core properties |
dcterms:created |
zero-or-one |
DateTime |
n/a |
n/a |
Timestamp of resource creation (reference: Dublin Core) |
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 foaf:Person but that is not necessarily the case. |
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 <div> element. This is intended to be a a human-readable description of the baseline. |
dcterms:identifier |
zero-or-one |
String |
n/a |
n/a |
An internal identifier, usually assigned by the service provider. If this property exists, its value SHOULD be unique amongst all currently existing baseline resources from this service provider. The string is not necessarily intended to be conveniently readable to humans. |
dcterms:modified |
zero-or-one |
DateTime |
n/a |
n/a |
Timestamp of the latest resource modification (reference: Dublin Core) |
dcterms:shortTitle |
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. |
dcterms:subject |
zero-or-many |
String |
n/a |
n/a |
Tag or keyword for a resource. Each occurrence of a dcterms:subject property denotes an additional tag for the resource. |
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 <span> element. This is intended to be a human readable name or synopsis of the baseline. |
Other common properties |
oslc:instanceShape |
zero-or-one |
Resource |
reference |
oslc:ResourceShape |
Resource Shape that specifies allowed and required fields. |
oslc:serviceProvider |
zero-or-one |
Resource |
reference |
oslc:ServiceProvider |
A link to the resource's OSLC Service Provider. |
oslc:readOnly |
zero-or-one |
Boolean |
n/a |
n/a |
A read-only state predicate indicating whether or not the resource is an immutable version or snapshot; if this value is true , the resource SHOULD NOT be modifiable. |
rdf:type |
one-or-many |
Resource |
reference |
n/a |
The resource type URI |
Baseline-specific properties |
rdfs:member |
zero-or-many |
Resource |
reference |
any |
A resource that is a member of this baseline. Such a resource SHOULD NOT be modifiable. |
Baseline Creation and Usage
- Clients create a Baseline resource by creating a HTTP POST request with the initial set of baseline properties to the baseline creation factory URI.
- Clients may add resources as members of a Baseline resource when that baseline is initially created using POST, or while it is under construction using PUT updates. Service providers SHOULD support the partial update protocol.
- The members added to a baseline do not have to be all from the same service, service provider, or OSLC domain - they can in fact be non-OSLC or non-RDF resources.
- A Baseline resource has
rdfs:member
links to one or more other resources that are members of the baseline. Any resource can be a member of a baseline, but since completed baselines should be immutable, clients SHOULD add as members only immutable resources, or mutable resources from the same service provider as the Baseline resource itself. One way to get immutable resources for Baselining is using the snapshot capability described earlier.
- An OSLC baseline service MUST provide a Baseline creation factory, and SHOULD provide a query capability that includes Baselines.
- A baseline service provider MUST implement the camera capability. Once a baseline construction has been completed, clients SHOULD get the URI of an immutable snapshot of this Baseline resource using the camera. This will also get immutable versions of members resources from the same service provider; as noted earlier, resources from other providers should already be immutable versions.
Making the contributing service providers rather than a baseline service from a different service provider responsible for creating versions or snapshots is a key characteristic of this proposal. Note that that it is possible for a client to "front-end" a service provider that doesn't currently support snapshots to add the capability, so this approach does not preclude integrating service providers that don't support snapshots or immutability, it just says that the baseline service does not provide this function.
Baseline membership traversal
The proposals above use the property
rdfs:member
for the immediate members of a baseline, and provider-specific properties for snapshot members and dependent resources.
When forming a baseline, a client can snapshot one or more resources, and then either add just the immediate snapshot results to a baseline, or add the immediate snapshot results and all their dependent members, recursively.
When examining the contents of a baseline, a client can look at the immediate members. From those immediate members, a client could find the service provider of any OSLC member resources with the
oslc:serviceProvider
property, inspect the
oslc:camera
property to find the dependent member property names, and recurse down finding dependent members. However, there is no guarantee that this procedure would find the complete set of baseline members intended by the clients that were involved in constructing the snapshots and baselines. For example, since the
oslc:serviceProvider
property is optional, the algorithm would not work for resources missing that property. Attempting to work around this issue by having clients add all dependent resources directly to the baseline does not seem to scale well as baselines are composed into even larger baselines across teams, components, products, and product lines.
Comments
Added my comments as
document attachment
Nick: Steve, I think all your comments were either addressed in the previous meeting, or incorporated into this updated proposal.
--
SteveSpeicher - 06 Apr 2011
Nick, regarding #6 above:
An OSLC baseline service MUST provide a Baseline creation factory, and SHOULD provide a Baseline query capability. To be compliant with the Indexer Profile, the service MUST provide a Baseline query capability.
Unl;ess I'm misunderstanding the intent, I'm not sure I agree with the last requirement ('To be compliant with the Indexer Profile, the service MUST provide a Baseline query capability.').
Or rather I don't believe it to be a mandatory requirement.
The snapshot resources, or the baseline resources themselves are ultimately resources that (if the service provider wants them to be - in other words they decide that they should be published resources) will already be exposed by a service provider implementing the indexing profile requirement that at least one Query Capability be exposed with a defined oslc:usage value (e.g. oslc:usage = "http://open-services.net/ns/core/log#resources")
I see that it may be useful for indices to be able to store data that excludes snapshotted resources (current version only) as well as to be able to store only snapshotted resources (be they from multiple baselines or just one) and so having Query Capabilities available that return relevant resource subsets for baselines would often be useful, I just don't know if it should be mandatory in the context of the indexing profile.
--
BenjaminWilliams - 06 Apr 2011
Nick: That sentence was intended to mean "If the provider intends to be compliant with the Indexer Profile, the service MUST provide a query base that includes Baseline resources." Since the change log proposal itself covers this requirement, it is redundant to state it here, so I have removed it.
dcterms:name is still in the list of properties but it doesn't exist, use oslc:shortTitle or rdfs:label or something else instead.
--
SteveSpeicher - 13 Apr 2011
Nick: lost that edit - now fixed!