OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

oslc-ccm message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [oslc-ccm] Review of change management spec

Thanks for the review - editor responses in <jra> tags

Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data

From:        "Sarabura, Martin" <msarabura@ptc.com>
To:        "OSLC CCM TC (oslc-ccm@lists.oasis-open.org)" <oslc-ccm@lists.oasis-open.org>
Date:        06/02/2016 10:56 AM
Subject:        [oslc-ccm] Review of change management spec
Sent by:        <oslc-ccm@lists.oasis-open.org>

Section 2.1:
- Partial Resource Representations: "... and MAY support via HTTP PUT" should be moved to the next line on Partial Update.
Appendix A.1:
- Deprecated terms not properly explained, and reference to CM 2.0 issues page contains no information on deprecation. I recommend that we include a short sentence for each deprecated term explaining why it is deprecated rather than relying on the hyperlink to the issues page.
- This sentence needs to start with the word "For":  Details about the reason for being marked as such and backwards compatibility items, refer to the CM 2.0 Issues page.
<jra>Hummm.... I couldn't find the anything that described the reasoning for the CM 2.0 deprecated terms, possibly because the open-services.net site was reorganized a couple of times, then work transitioned to OASIS. These terms were actually deprecated during the development of CM 2.0. Its not clear these need to be carried over into 3.0 as they were deprecated in a previous version, CM 3.0 is not deprecating anything new.

I changed the introductory text to indicate the terms were deprecated in 2.0 and remain deprecated in this version. The history for why may be lost and probably isn't that relevant since this was addressed in 2.0 finalization, not introduced in 3.0.</jra>
Appendix A.2:
- Add "Terms deprecated but not removed from the specification."
<jra>These are terms that were added in 3.0, not deprecated from 2.0 but kept. This is intended to simply highlight these upward compatible changes to 2.0. I added some clarifying description.</jra>
In the vocabulary terms document:
Section 1.3:
- oslc_qm namespace is never referenced from the document. We can remove that note in section 1.3.
<jra>It is referenced many times in the vocabulary properties generated by ReSpec from the .ttl file, e.g., It is likely that the target resource will be an oslc_qm:TestCase. </jra>
Section 3:
- Problems with this sentence: affects - Indicates that the Change Request affects, has been predetermined to have impact, related resource. These property relationships can be used to understand the potential impact of referenced resources.
<jra>Fixed: Indicates that the Change Request affects, or has been predetermined to have impact on, the related resource. These property relationships can be used to understand the potential impact of referenced resources.</jra>
Section 3.1:
- I think a reference to informational reference [OSLCQM] is appropriate here. If not, then there is no reference to [OSLCQM] anywhere else in the document and it should be removed from the list of informational references.
<jra>The informative reference to OSLCQM is to provide additional informaiton on the oslc_qm namespace which is used in the property descriptions</jra>
Sections 3.1 et seq:
- Shouldn't we provide a UML diagram showing common terms on the abstract base class and the terms that are specific to each type of resource on the concrete instances? It's hard to compare - and natural to want to do so especially if you are a developer trying to conform to the spec.
<jra>I will create a UML diagram and add it</jra>
Section 3.6:
- State never referenced elsewhere in the document
- State does not include "Rejected" - I believe it should.
<jra>Looks like this was a breaking change in CM 3.0 that I missed. It is left over from the attempt to use OSLC Actions to define valid state transitions on oslc_cm:status. See its description: "Used to indicate the status of the change request. This property is read-only, but can be changed using actions." We decided to defer this feature, so the following changes need to be done:

1. oslc_cm:status should have its original description: Used to indicate the status of the change request based on values defined by the service provider. Most often a read-only property. Some possible values may include: 'Submitted', 'Done', 'InProgress', etc. "

2. I introduced enumeration oslc_cm:Status to be used as the range for property oslc_cm:status in the shapes file.  Section 3.6 erroneously uses State, In-progress should be InProgress, and the case of the enumeration literals should be upper case in the shapes.ttl file to be consistent with other enumeration literals. You can add whatever enumeration values you want, CM 3.0 just specifies the minimal standard set of values.

3. Looking at this closer though, there are additional issues. CM 2.0 defines oslc_cm:status to be a String, and therefore we cannot change its range to oslc_cm:Status with enumeration values (URLs) as this would introduce an incompatibility. In addition, CM 2.0 also defines a number of boolean properties oslc_cm:closed (not oslc_cm:Closed which is an instance of oslc_cm:Status) that were removed because of the introduction of enumeration oslc_cm:Status. These properties will need to be put back, and oslc_cm:Status should probably be removed.

I'll raise an issue on this since it should be discussed. OSLCCCM-23
Section 3.7 and 3.8:
- Following needs to be fixed: "NEEDS UPDATE: Improve descriptions."
<jra>Fixed, using the descriptions of the enumeration literal values in the vocabulary.</jra>

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]