Change Management Resources Definition V2.0

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.

Change Request Resource

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.

XML namespace abbreviations used in this specification:

• oslc_cm - The Open Services for Lifecycle Collaboration Change Management namespace - http://open-services.net/xmlns/cm/1.0 /
• rdf - RDF XML namespace - http://www.w3.org/1999/02/22-rdf-syntax-ns#
• dc - The Dublin Core Metadata Terms namespace - http://purl.org/dc/terms/

Resource Definition for: =ChangeRequest=
Property	Type	Occurs	Description
See OSLC Common Properties
dc:identifier	String	exactly-one, readOnly	The required, read-only identifier string. This is assigned by a change management system when a request resource has been created.
dc:type Same as rdf:type?	URI	zero-or-more	The type of request that is represented, such as: defect, enhancement, etc.
dc:subject	String	zero-or-more	The optional subject string. The DC namespace defines this element to be a collection of keywords. The subject element will contain keywords and tags assigned to this request.	Todo this should utilize a common tagging service
dc:name	String	at-most-one	The optional short name that is often used for an abbreviated identifier and used for presentation to end-users.
doneDate	Date Time	at-most-one	The optional, read-only modified date time which must conform to RFC3339 format	Todo can the question "is this done?" be assumed to be answered if this property is not null
project	any	zero-or-many	The optional reference to a project resource. A project is defined to be a contextual configuration container for change requests. Its purpose and definition may be extended	Todo circle with PPM domain, perhaps we should just call this container as an abstract and providers can label it as they please. Though foaf:Project and DOAP should be explored.
component	any	zero-or-many	The optional reference to a component resource. A component is defined to be a sub-context of a project, used to further scope change request resources.	Todo circle with PPM/SCM domains
status	String	at-most-one	May be a read-only field that gets modified by performing an "action" or "operation", this is how most CM providers work
priority	any	at-most-one
severity	any	at-most-one
attachments	Resource Attachments	at-most-one	Todo this should be a common approach/service.
comments	Resource Comment	at-most-one		N/A
open	boolean	at-most-one, readOnly	Whether or not the resource is in an opened or closed state	N/A
inprogress	boolean	at-most-one, readOnly	Whether or not the resource in a state indicating that active work is occurring	N/A
fixed	boolean	at-most-one, readOnly	Whether or not the resource has been fixed	N/A
validated	boolean	at-most-one, readOnly	Whether or not the resource has been validated	N/A
approved	boolean	at-most-one, readOnly	Whether or not the resource has been approved	N/A
reviewed	boolean	at-most-one, readOnly	Whether or not the resource has been reviewed	N/A
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

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

• Property name: relatedChangeRequests
• Name: RelatedChangeRequests?
• Namespace URI: =http://open-services.net/xmlns/cm/2.0#
• Type URI: =http://open-services.net/xmlns/cm/2.0#RelatedChangeRequest
• 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>

dc:creator

The dc:creator property represents indirectly a person who was responsible for the bringing the associate change request into existence. The creator could be a person (real or not) in which an agent acts, such as automated processes for change request creation. The CM provider either natively provide dc:creator resource or a link to a referenced to one, the identifies key information about the user.

The content definition for dc:creator :

type	foaf:Person
minOccur	0
maxOccur	1
writable	no

Example (referenced)

  <dc:creator rdf:resource="http://myserver/mycmapp/users/joe" />

Example (inlined)

  <dc:creator>
    <foaf:Person rdf:about="http://myserver/mycmapp/users/joe">
      <foaf:name>Joe Name</foaf:name>
      <foaf:nick>joe</foaf:nick>
      <foaf:mbox rdf:resource="mailto:joe@nowhere" />
      <foaf:img rdf:resource="/user-images/joen.jpg" />
    </foaf:Person>
  </dc:creator>

dc:contributor

The dc:contributor property represents indirectly a person who is responsible for coordinating the completion of the change request.

The content definition for dc:contributor :

type	foaf:Person
minOccur	0
maxOccur	1
writable	yes

Example (referenced)

  <dc:contributor rdf:resource="http://myserver/mycmapp/users/bob" />

Example (inlined)

  <dc:contributor>
    <foaf:Person rdf:about="http://myserver/mycmapp/users/bob">
      <foaf:name>Bob Boss</foaf:name>
      <foaf:nick>bob</foaf:nick>
      <foaf:mbox rdf:resource="mailto:bob@nowhere" />
      <foaf:img rdf:resource="/user-images/bobb.jpg"/>
    </foaf:Person>
  </dc:contributor>

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>
  <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:owner rdf:resource="http://myserver/mycmapp/users/bob" />
  <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" : "mailto:aadams@someemail.com",
 "dc:modified" : "2008-09-16T08:42:11.265Z"
}  

TODO Outstanding issues:

1. How to discover unsupported properties, some CM providers don't support some of these concepts
   • Resource Shapes
2. 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)
3. Align possible common cross-domain items:
   1. Add Comment/Discussion (should be a cross domain resource type)
   2. Project/component is cross-domain topic
   3. Attachments is cross-domain topic
4. Align collection support from EM + RM, with @collref in CM
   1. See examples MetricsCollectionsInRDFXML
   2. See CmCollectionNeeds
5. Best way of handling multi-valued properties like: relatedChangeRequests
6. Determine how much resource link data is needed for things like relatedChangeRequests.
7. (defer) Resolve changeset resource link with SCM domain