2.0 Early Working Draft This early working draft is building off the V1.0 definition for Change Request to expand on work done based on common properties used by many CM tools and key scenarios for next versions of specification
Introduction
Change Management resources define the change requests and tasks of the software delivery lifecycle. This specification will focus on the definition of a change request, which includes common set of properties, their types and requirements on usage. Implementations can extend this base definition of a change request by contributing their additional properties to the change request resource defintion.
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. Domain name examples use
RFC2606.
Terminology
Change Request - A request for change to an application or product. Typically a product request for enhancement or a report for a resolution of a product defect.
XML namespace abbreviations used in this specification:
Resource: Change Request
The change request resource properties are not limited to the ones defined in this specification. It is recommended to contribute resource properties in their own unique namespace, not to reuse those defined in these specifications.
- Name:
ChangeRequest
- Suggested Prefix:
oslc_cm
- Namespace URI:
http://open-services.net/xmlns/cm/2.0#
- Type URI
http://open-services.net/xmlns/cm/2.0#ChangeRequest
- Version String:
oslc-cm-2.0
- Properties:
Property |
Type |
Occurs |
Description |
dc:type |
URI |
zero-or-more |
The type of request that is represented, such as: defect, enhancement, etc. Same as rdf:type |
dc:identifier |
String |
exactly-one, readOnly |
This is assigned by a change management system when a request resource has been created. |
dc:name |
String |
at-most-one |
Short name that is often used for an abbreviated identifier and used for presentation to end-users. |
dc:subject |
String |
zero-or-more |
Contain keywords and tags assigned to this request. |
doneDate |
Date Time |
at-most-one, readOnly |
What is the definition of done ? Leave to service? |
project |
any |
zero-or-many |
A project is defined to be a contextual configuration container for change requests. Its purpose and definition may be extended |
component |
any |
zero-or-many |
A component is defined to be a sub-context of a project, used to further scope change request resources. |
status |
String |
at-most-one |
May be a read-only field that gets modified by performing an action |
priority |
any |
at-most-one |
A relative prioritization of this change request compared to others |
severity |
any |
at-most-one |
The impact or severity of this change request |
attachments |
Resource Attachments |
at-most-one |
A collection of files that associated to this change request |
comments |
Resource Comment |
at-most-one |
A sequence of notes and discussions about this change request |
open |
boolean |
at-most-one, readOnly |
Whether or not the resource is in an opened or closed state |
inprogress |
boolean |
at-most-one, readOnly |
Whether or not the resource in a state indicating that active work is occurring |
fixed |
boolean |
at-most-one, readOnly |
Whether or not the resource has been fixed |
validated |
boolean |
at-most-one, readOnly |
Whether or not the resource has been validated |
approved |
boolean |
at-most-one, readOnly |
Whether or not the resource has been approved |
reviewed |
boolean |
at-most-one, readOnly |
Whether or not the resource has been reviewed |
Link Properties |
Type |
Occurs |
Description |
Context Link |
Reciprocal Property |
relatedChangeRequests |
Resource RelatedChangeRequests? |
at-most-one |
Related change requests, no special semantics |
relatedTo |
relatedChangeRequest |
manages |
Resource Manages |
at-most-one |
Manages the associated resources |
manages |
managedBy |
implementsRequirements |
Resource LinkCollection? ImplementsRequirements? |
at-most-one |
Implements associated Requirement |
implements |
implementedBy |
testedByTestCases |
Resource LinkCollection? TestedByTestCase? |
at-most-one |
Test case by which this change request is tested |
testedBy |
tests |
affectsTestCases |
Resource LinkCollection? AffectsTestCases? |
at-most-one |
Associated QM resource that is affected by this Change Request |
testedBy |
affectedBy |
blocksTestCases |
Resource LinkCollection? BlocksTestCases? |
at-most-one |
Associated QM resource that is blocked by this Change Request |
testedBy |
blockedBy |
changeSets (defer) |
|
|
*Todo* circle with SCM topic |
scm |
cm |
changeSets |
Context Link when refers to the contextual property link that exists to a service provider defined context
Reciprocal Property is a property on the linked to resource can may be used to store an additional link back to source change request resource.
Link Collections
Conceptual Model
Certain properties of a Change Request resource are defined using an intermediate collection to be able to be able to allow for requesting a minimal representation of the Change Request and allow for independent management of the collection's properties.
To add additional link values to the link collection, services MAY support POST on the collection URI with the request body containing at least one link property value. Upon successful addition of link property values, the service MUST respond with a HTTP status code 201-Created and MAY include a URI in the Location header representing the additional properties created.
POST http://myserver/mycmapp/bugs/2314/related
Content:
<oslc_cm:relatedChangeRequest rdf:resource="http://myserver/mycmapp/bugs/1235"/>
To remove link values from the collection, services MAY support DELETE on a URI which represents a specific link value using Query Syntax (oslc.where).
DELETE http://myserver/mycmapp/bugs/2314/related?oslc.where=<http://myserver/mycmapp/bugs/1235>
Service MAY allow retrieval of all link values by performing a GET on the link collection URI. Service MAY allow update of the link collection by performing a subsequent PUT.
relatedChangeRequests
- Name:
RelatedChangeRequests
- Namespace URI:
http://open-services.net/xmlns/cm/2.0#
- Type URI:
http://open-services.net/xmlns/cm/2.0#RelatedChangeRequest
- Parent property name:
relatedChangeRequests
- Properties:
- relatedChangeRequest (Resource ChangeRequest? , zero-or-more): A related Change Request resource
Sample: Not inlined
<oslc_cm:ChangeRequest>
<oslc_cm:relatedChangeRequests rdf:resource="http://myserver/mycmapp/bugs/2314/related" />
</oslc_cm:ChangeRequest>
Sample: Inlined
<oslc_cm:ChangeRequest>
<oslc_cm:relatedChangeRequests>
<oslc_cm:RelatedChangeRequests rdf:about="http://myserver/mycmapp/bugs/2314/related">
<oslc_cm:relatedChangeRequest rdf:resource="http://myserver/mycmapp/bugs/1235" />
<oslc_cm:relatedChangeRequest rdf:resource="http://remoteserver/mycmapp/defects/abc123" />
</oslc_cm:RelatedChangeRequests>
</oslc_cm:relatedChangeRequests>
</oslc_cm:ChangeRequest>
Contextual Relationship Properties
These properties are intended to be part of Service Resource to identify the link collections that are used to identify which repository connections have been established and their associated purpose. These properties are used in conjunction with the link properties in the Change Request Resource.
Properties |
Type |
Occurs |
Description |
Reciprocal Property |
relatedTo |
Resource ServiceProvider? |
at-most-one |
|
relatedTo |
manages |
Resource ServiceProvider? |
at-most-one |
Manages the associated resources |
managedBy |
implementsRequirements |
Resource ServiceProvider? |
at-most-one |
|
implementedBy |
testedBy |
Resource ServiceProvider? |
at-most-one |
Test case by which this change request is tested |
tests |
* Reciprocal properties identify properties on a connected service provider. It may be desirable for a provider that owns the relationship, to update a reciprocal property that is referenced.
Reciprocal context properties are identified in a Service Provider resource:
<oslc:service>
<oslc:Service>
<oslc:domain>http://open-services.net/xmlns/cm#</oslc:domain>
... snip ....
<oslc_cm:relationships>
<oslc_cm:Relationships>
<oslc_cm:relatedTo rdf:resource="http://myhost/project/1/relatedTo" />
<oslc_cm:manages rdf:resource="http://myhost/project/1/manages" />
<oslc_cm:implements rdf:resource="http://myhost/project/1/implements" />
<oslc_cm:testedBy rdf:resource="http://myhost/project/1/testedBy" />
</oslc_cm:Relationships>
</oslc:relationships>
</oslc:Service>
</oslc:service>
XML Representation of the Change Request Resource
The media type used for this representation MAY be
application/rdf+xml
or
application/x-oslc-cm-change-request+xml
Example
<?xml version="1.0" encoding="UTF-8"?>
<oslc_cm:ChangeRequest
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/terms/"
xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/"
rdf:about="http://example.com/bugs/2314">
<dc:title> Provide import </dc:title>
<dc:identifier> 2314 </dc:identifier>
<dc:type> http://myserver/mycmapp/types/Enhancement </dc:type>
<dc:description>
Implement the system's import capabilities.
</dc:description>
<dc:subject> import, blocker </dc:subject>
<dc:creator rdf:resource="http://myserver/mycmapp/users/joe" />
<dc:modified> 2008-09-16T08:42:11.265Z </dc:modified>
<!-- Proposed new properties for 2.0 -->
<dc:name>Enh2314: Provide import</dc:name>
<dc:created> 2008-07-04T11:00:00.000Z </dc:created>
<dc:contributor rdf:resource="http://myserver/mycmapp/users/bob" />
<oslc_cm:doneDate> </oslc_cm:doneDate> <!-- Done/Completion date -->
<oslc_cm:project rdf:resource="http://myserver/mycmapp/projects/proj1" />
<oslc_cm:component rdf:resource="http://myserver/mycmapp/projects/proj1/comps/comp1" />
<oslc_cm:status> InProgress </oslc_cm:status>
<oslc_cm:priority> High </oslc_cm:priority>
<oslc_cm:severity> Blocker </oslc_cm:severity>
<oslc_cm:attachments rdf:resource="http://myserver/mycmapp/files/23456" />
<oslc_cm:comments rdf:resource="http://example.com/bugs/2314/discussion" />
<oslc_cm:relatedChangeRequests>
<oslc_cm:RelatedChangeRequests rdf:about="http://myserver/mycmapp/bugs/2314/related">
<oslc_cm:relatedChangeRequest rdf:resource="http://myserver/mycmapp/bugs/1235" />
<oslc_cm:relatedChangeRequest rdf:resource="http://remoteserver/mycmapp/defects/abc123" />
</oslc_cm:RelatedChangeRequests>
</oslc_cm:relatedChangeRequests>
<oslc_cm:manages>
<oslc_cm:Manages rdf:about="http://myserver/mycmapp/bugs/2314/manages">
<oslc_cm:manage rdf:resource="http://myserver/scmtool/cs/34ef31af" />
<oslc_cm:manage rdf:resource="http://remoteserver/cvsrepo/changeset/cs1" />
</oslc_cm:Manages>
</oslc_cm:manages>
</oslc_cm:ChangeRequest>
JSON Representation of the Change Request Resource
The media type used for this representation SHOULD be
application/json+xml
or
application/x-oslc-cm-change-request+json
.
Example
{
"rdf:about": "http://example.com/bugs/2314",
"dc:title": "Provide import",
"dc:identifier" : "2314",
"dc:type" : "http://myserver/mycmapp/types/Enhancement",
"dc:description" : "Implement the system's import capabilities.",
"dc:subject" : "import, blocker",
"dc:creator" : "http://myserver/mycmapp/users/joe",
"dc:modified" : "2008-09-16T08:42:11.265Z"
}
TODO Outstanding issues:
- How to discover unsupported properties, some CM providers don't support some of these concepts
- How to fold new elements in: new namespace for just new elements? just add them? new namespace for ChangeRequest? root element? (how will 1.0 consumers fallback)
- Align possible common cross-domain items:
- Add Comment/Discussion (should be a cross domain resource type)
- Project/component is cross-domain topic
- Attachments is cross-domain topic
- Align collection support from EM + RM, with @collref in CM
- See examples MetricsCollectionsInRDFXML
- See CmCollectionNeeds
- Best way of handling multi-valued properties like: relatedChangeRequests
- Determine how much resource link data is needed for things like relatedChangeRequests.
- (defer) Resolve changeset resource link with SCM domain