OSLC QM Spec V2 Issues

This section captures the issues raised via review comments on:

• QmSpecificationV2 - the OSLC-QM V2.0 Specification Draft

Issues are organized via the spec outline.

Note: dates below use US format (mm/dd/yyyy)

Here's what the states mean:

• OPEN - indicates that we have no response for the issue yet
• RESOLVED - indicates that we have a response that we believe resolves the issue
  • RESOLVED - indicates it is resolved as by above definition and edits in the draft specification have been made.
• CLOSED - issue has been resolved and the resolution has been reviewed by the workgroup
• DEFERRED - indicates that issue will be addressed in guidance after the specification converges
• TABLED - indicates that issue will be reconsidered at some later but unspecified date

Overall

1. OPEN Sample/template issue (copy and paste) (WikiName? , mm/dd/2010)
   • Response Need response (PaulMcMahan mm/dd/2010)

Base Requirements

1. CLOSED Specification versioning - the text in this section specificies both a core version and an oslc-qm version. Though this approach was originally proposed, the conclusions of the core workgroup on this subject found that only the core version was needed. The core guidance on versioning can be found at http://open-services.net/bin/view/Main/OSLCCoreSpecDRAFT?sortcol=table;up=#Specification_Versioning. (ScottBosworth, 07/12/2010)
   • Response Removed oslc-qm version from the spec. See Specification Versioning (PaulMcMahan 07/13/2010)
2. CLOSED We could potentially continue to provide support for QM V1 consumers by requiring that they send the QM V1 Accept headers. And if a client requests application/xml then they would be sent the special RDF subset format from V2. This would allow the service provider to use HTTP headers to satisfy three types of consumers: V1 clients, V2 clients needing the constrained form XML (e.g. web browsers), and V2 clients that support any valid RDF/XML (PaulMcMahan, 07/26/2010).
   • Response QM V1 clients may not be sending the oslc-qm-* Accept headers to service providers since the V1 spec did not include any language indicating they should do so. Even clients that do send those headers would probably not send them for the V1 service discovery documents, which have changed substantially. Therefore the language in the V2 spec still requires the OSLC-Core-Version header. (PaulMcMahan 08/20/2010)

QM Resource Definitions

1. CLOSED The use of extended properties as described in the core spec raises concerns since it requires clients to "know" about those properties in advance. This conflicts with the goal of making OSLC properties easily discoverable by web crawlers and the like. (PaulMcMahan, 07/06/2010)
   • Response Removed extended properties from the spec (PaulMcMahan, 07/06/2010)
2. CLOSED Resource relationship properties - it would be useful to make the picture of the QM resources and their relationships more prominent in this specification. Also, the current defined set of relationships may go further what is minimally needed to support the QM V2 scenarios. For example, the QM scenarios (QmScenariosTraceability, QmScenariosExecution) do not seem to indicate any relationship between a Test Case resource and a Test Result resource (instead, there is a relationship between a Test Plan and a Test Execution Record, and between a Test Execution Record and a Test Result), yet this relationship is specified. If wonder if a detailed walkthrough of the resources and the needed relationships should be a topic of a future workgroup meeting? (ScottBosworth, 07/12/2010)
   • Response The relationship properties were originally proposed when the concept of "extended properties" was available. By defining the relationship properties as extended the service provider was able decide which properties would show up in the resource by default, and (at least in my thinking) also affected whether or not a relationship was queryable. Now that the concept of extended properties is no longer available I took another look at the scenarios and rethought the relationships in terms of scalability and performance. I also added the diagram directly into the specification rather than only listing as an attachment. See Resource Definitions (PaulMcMahan 07/13/2010)
3. CLOSED Test Case, Test Script, Test Execution Record, Test Result - these resource definition contain only common properties (like title and creator), and relationship properties, and do not have properties that expose other details of a test case, script, execution record, or result. This may be all that is needed in support of integration scenarios, but it surprised me a bit. I had expected to see more properties for these resources (e.g. for a test script, a url reference to a human readable step-by-step process or a reference to the executable). Do the V2 scenarios suggest a need for additional properties on these resources? (ScottBosworth, 07/12/2010)
   • Response Added configuration property (relationship) for Test Execution Record. Added executablePath and executionInstructions for Test Script. There is a "status" property for TestResult. (PaulMcMahan 07/25/2010)
4. CLOSED relatedChangeRequest relationship properties are not symmetrical with the naming convention used in the CM spec. CM spec uses tracksXX. (PaulMcMahan, 07/14/2010)
   • Response The CM spec has been updated to use relatedTestPlan, relatedTestCase, etc... (PaulMcMahan 07/26/2010)
5. CLOSED The possible values used for "occurs" column in the QM resource definition table do not correspond to those specified in the Core Spec (Core uses 'exactly-one', 'zero-or-one', 'one-or-many' or 'zero-or-many'). (ScottBosworth, 07/26/2010)
   • Response Corrected the table (PaulMcMahan mm/dd/2010)
6. CLOSED oslc_qm:executablePath property of TestScript? resource. Should this be in the "relationship properties" section of properties? The property name and description implies some sort of file path - would a more appropriate relationship property name simply be oslc_qm:executionScript (to mirror the oslc_qm:executionInstructions relationship)? Would a better description be "Test execution script"? (ScottBosworth, 07/26/2010)
   • Response Generalized the use of executionInstructions to reference either a human readable list of instructions (xhtml, pdf, etc) or machine readable (sh script, javascript, executable code, etc). Removed executablePath. Added a comment about the value of Occurs being unspecified in the spec. (PaulMcMahan 08/20/2010)
7. CLOSED The spec needs to clarify the behavior of Accept headers. The CM spec has a good example CmSpecificationV2#Media_Types. Noted for DragosCojocari (PaulMcMahan, 08/13/2010)
   • Response clarified the use of accept headers (PaulMcMahan 08/20/2010)
8. CLOSED Some of the language in the spec does not coincide with the values in the QmSpecificationV2#Compliance section. For example the Compliance section requires the service provider to support RDF/XML but other language in the spec implies that it is optional. (PaulMcMahan 08/20/2010)
   • Response aligned the language about RDF/XML with the compliance section (PaulMcMahan 08/20/2010)
9. CLOSED Per Core workgroup guidance on relationships and links, we need to clarify in the specification where link properties have URI endpoints that must be of a certain type or may be of any type. (ScottBosworth 10/06/2010)
   • Response updated all link properties in the QM resources to indicate when clients can expect a specific type of resource at the uri endpoint (e.g. serviceProvider) and when clients cannot make assumptions about the type of resource at the uri endpoint (e.g. dcterms:creator, oslc_qm:relatedChangeRequest). (ScottBosworth 10/06/2010)
10. CLOSED A couple of small typos in the resource property descriptions:

• Creator: Add a space between resource (reference: Dublin Core).
• Modified: Replace last with of.
• Response corrected (PaulMcMahan 12/02/2010)

Miscellaneous

1. CLOSED Media types - this section is not clear on the intended use of media types. I think we're looking to deprecate the use of the OSLC-QM V1 media types and shift to standard media types with V2. Can this section offer guidance on those intentions and the specific behavior expected of OSLC V1 and V2 consumers and providers that are being integrated in different combinations? (ScottBosworth, 07/12/2010)
   • Response Provided clarification that the OSLC QM V1 media types are being deprecated. The supported media types for OSLC QM V2 will be application/xml and application/rdf+xml (PaulMcMahan 07/25/2010)
2. CLOSED -A couple of issues with 'OSLC Quality Management 2.0 Appendix B: Resource Shapes' (http://open-services.net/bin/view/Main/QmSpecificationV2Shapes) (PaulSlauenwhite 09/02/2010):
   • Response PaulSlauenwhite contributed an example shapes document that addresses his concerns. (PaulMcMahan 12/02/2010)
   • The test plan (http://open-services.net/bin/view/Main/QmSpecificationV2Shapes?sortcol=table;up=#TestPlan) and test case (http://open-services.net/bin/view/Main/QmSpecificationV2Shapes?sortcol=table;up=#TestCase) sections should be be swapped. However, looks like the relationship properties are correct.
     • Response corrected (PaulMcMahan 09/16/2010)
   • Abbreviated RDF+XML (see example XML) does not contain rdf:type elements and contains rdf:datatype attributes.
   • A comment should be added mentioning that example XML show unencoded/unescaped values and use abbreviated RDF+XML for clarity.
   • Replace http://http:// with http://.
     • Response corrected (PaulMcMahan 09/16/2010)
   • Correct the indentation of dcterms:title properties within the oslc:Property resources.
     • Response corrected (PaulMcMahan 09/16/2010)
     • Response one more remaining (Test Plan's contributor).
   • Add <oslc:valueShape rdf:resource="<resource shape URI>"/> for all resources (Resource/AnyResource value types).
   • The dcterms:identifier, rdf:type, oslc:serviceProvider, and oslc:instanceShape properties within the oslc:Property resources should be hidden since they are not intended for end-user display.
   • The title should be title case (e.g. This is a Title) instead of sentence case (e.g. This is a title).
   • Change http://open-services.net/ns/cm to http://open-services.net/xmlns/cm/1.0.
   • Change http://open-services.net/ns/rm to http://open-services.net/xmlns/rm/1.0.
   • We should add all optional properties for completeness. For example: QM_Resource_Shapes.txt