This wiki is locked. Future workgroup activity and specification development must take place at our new wiki. For more information, see this blog post about the new governance model and this post about changes to the website.

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.

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:

  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
Edit | Attach | Print version | History: r17 < r16 < r15 < r14 < r13 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r14 - 12 Apr 2010 - 20:03:29 - SteveSpeicher
 
This site is powered by the TWiki collaboration platform Copyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use
Ideas, requests, problems regarding this site? Send feedback