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
- From: "Jim Amsden" <jamsden@us.ibm.com>
- To: "OSLC CCM TC (oslc-ccm@lists.oasis-open.org)" <oslc-ccm@lists.oasis-open.org>
- Date: Fri, 3 Jun 2016 16:47:52 -0400
Martin,
Thanks for the review - editor responses
in <jra> tags
Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575
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.
<jra>fixed</jra>
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
</jra>
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]