TWiki> Main Web>CmHome>CmResourceDefinitionsV2 (27 Jan 2010, SteveSpeicher)EditAttach

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:

XML Representation of the Change Request Resource

The media type used for this representation MUST be application/x-oslc-cm-change-request+xml.

XML Representation Summary: ChangeRequest Element
Property Representation Notes
dc:title The required title string. Note that this element comes from the DC namespace, allowing tools unaware of the change management domain to access this element. This is sometimes also referred to as the headline or summary of the request.  
dc:identifier The required, read-only identifier string. This is assigned by a change management system when a request resource has been created.  
dc:type The optional type string. The type of request that is represented, such as: defect, enhancement, etc.  
dc:description The optional description string. This element comes from the DC namespace, allowing tools completely unaware of the change management domain to access this element.  
dc:subject 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:creator The optional, read-only creator element, identifying the originating user of this request.  
dc:modified The optional, read-only modified date time which must conform to RFC3339 format  
dc:name The optional short name that is often used for an abbreviated identifier and used for presentation to end-users.  
dc:created The required, read-only creation date time indicating when the resource was created within the service provider, whose format must conform to RFC3339  
doneDate 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 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 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   May be a read-only field that gets modified by performing an "action" or "operation", this is how most CM providers work
owner    
priority    
severity    
attachments   Todo this should be a common approach/service.
relatedChangeRequests    
changeSets   Todo circle with SCM topic
comments    

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>

References:

Todo: Outstanding items:

  • General agreement on foaf:Person is enough as there are not too many systems that have multiple accounts per user. Can be managed by having separate person instances (exception, instead of the rule)
  • Align with other definitions of Users: OpenSocial.Person, portable contacts
  • Elaborate on usage and reference of these URLs for cross-repositories correlation. Two separate CM providers, one has a reference to a "user" and how to make sure it is same user across systems.
  • Need to further refine how much of referenced vocab providers need to support.
    • Needed properties on a person: first and last name, account id, email address: others possible: phone #, web url, language
    • Need to make sure FOAF:Person is extensible as well

oslc_cm:owner

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

The content definition for oslc_cm:owner :

type foaf:Person
minOccur 0
maxOccur 1
writable yes

Example (referenced) 

  <oslc_cm:owner rdf:resource="http://myserver/mycmapp/users/bob" />

Example (inlined) 

  <oslc_cm:owner>
    <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>
  </oslc_cm:owner>

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:ChangeRequest>
      <oslc_cm:relatedChangeRequests rdf:resource="http://myserver/mycmapp/bugs/1235" />
      <oslc_cm:relatedChangeRequests rdf:resource="http://remoteserver/mycmapp/defects/abc123" />
    </oslc_cm:ChangeRequest>
  </oslc_cm:relatedChangeRequests>
  
  <oslc_cm:changeSets>
    <oslc_cm:ChangeSet>
      <oslc_cm:changeSet rdf:resource="http://myserver/scmtool/cs/34ef31af" />
      <oslc_cm:changeSet rdf:resource="http://remoteserver/cvsrepo/changeset/cs1" />
    </oslc_cm:ChangeSet>
  </oslc_cm:changeSets>
      
</oslc_cm:ChangeRequest>

JSON Representation of the Change Request Resource

The media type used for this representation MUST be application/x-oslc-cm-change-request+json.

JSON Representation Summary: ChangeRequest? JSON Object
{ Content: (dc:title, dc:identifier, dc:type?, dc:description?, dc:subject?, dc:creator?, dc:modified?) }
Property Representation
rdf:about
The optional URI of this resource.
dc:title The required title string. Note that this element comes from the DC namespace, allowing tools unaware of the change management domain to access this element. This is sometimes also referred to as the headline or summary of the request.
dc:identifier The required, read-only identifier string. This is assigned by a change management system when a request resource has been created.
dc:type The optional type string. The type of request that is represented, such as: defect, enhancement, etc.
dc:description The optional description string. This element comes from the DC namespace, allowing tools completely unaware of the change management domain to access this element.
dc:subject 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.
dc:creator The optional, read-only creator element, identifying the originating user of this request.
dc:modified
The optional, read-only modified date time which must conform to RFC3339 format
TODO Add New

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. See various Todo items in table above
  2. How to discover unsupported properties, some CM providers don't support some of these concepts
  3. Map proposed properties to existing vocabs: DC, FOAF, DOAP, MOT, ...
  4. 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)
  5. 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
  6. Resolve changeset resource link with SCM domain
  7. Align collection support from EM + RM, with @collref in CM
    1. See examples MetricsCollectionsInRDFXML
    2. See CmCollectionNeeds
  8. Best way of handling multi-valued properties like: relatedChangeRequests
  9. Determine how much resource link data is needed for things like relatedChangeRequests.
  10. Resource model for properties of type "User" like creator and owner. One approach: leverage FOAF.
Edit | Attach | Print version | History: r8 < r7 < r6 < r5 < r4 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r8 - 27 Jan 2010 - 15:15:58 - 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