[cddlm] deploy API revisions

Thu Mar 23 02:26:23 CST 2006

Hi Dejan,

Sorry for the last minutes comments. They are all minor editorial
ones. Please see attached file.

Thanks,
----
Hiro Kishimoto

Milojicic, Dejan S (HP Labs) wrote:
> Hi CDDLM Community and the Team Members,
> 
> I was requested by the GGF leaders to formally post the last call before
> the resubmission of the deployment-api spec. Please let me know before
> the end of the week if you have any comments. I have attached the
> documents that Steve posted as well as the Word document which slightly
> differ (file name and abstract to match other documents and original
> submission).
> 
> Thanks,
> 
> Dejan.
> 
>>-----Original Message-----
>>From: owner-cddlm-wg at ggf.org [mailto:owner-cddlm-wg at ggf.org] 
>>On Behalf Of Steve Loughran
>>Sent: Wednesday, March 15, 2006 7:42 AM
>>To: 'cddlm-wg at ggf.org'
>>Subject: [cddlm] deploy API revisions
>>
>>
>>Dejan (and others)
>>
>>This is the updated document. The -changes PDF highlights 
>>where the changes have taken place; the normal PDF is the 
>>actual document that should be used with the standard.
>>
>>The text document comments on the corrections.
>>
>>-steve
>>
>>
>>
>>------------------------------------------------------------------------
>>
>>
>>Overall, these comments are a welcome application of rigorousness to the
>>use of the RFC2119 keywords to the document, highlighting when they are
>>not used where they are needed, and indicated places where their use is
>>inappropriate. with one exception all of the changes are minor, and 
>>do not change any of the semantics of the specification, merely reduce
>>ambiguity.
>>
>>The biggest change is in section 7.2.1, in which the "scheme" element 
>>representing a URL scheme was misspelled as "schema". 
>>This is part of the public deployment API XML Schema:
>>changing it will affect the implementations, but not the semantics of
>>the actual implementation. Members of all four implementation teams
>>were consulted over the change, and agreed that it was minor and that
>>it should take place immediately.
>>
>>In the process of updating the document I also
>> -changed the date to 2006
>> -updated the copyright years
>> -corrected an error in which a code sample had merged with the following
>> paragraph, and was not marked as code.
>>
>>----------------------
>>
>>
>>
>>The following is my comments on the 2005-09-13 draft of the Deployment API. 
>>The comment format is similar to the Aardvark Comment Format described in the 
>>following page: 
>> 
>>http://www.opengroup.org/austin/aardvark/format.html 
>> 
>> 
>>@ page 10 section 3.4.3.3 Extra deployment options 
>> 
>>Problem: 
>>  In the 1st item of the bullet list, the following sentence: 
>> 
>>    Every option is named by a URI. 
>> 
>>  does not contain RFC2119 keyword. 
>> 
>>To fix: 
>>  Change the sentence as follows: 
>> 
>>    Every option MUST be named by a URI. 
>> 
>>    
>>-fixed as advised.
>>    
>>    
>>@ page 10 section 3.4.3.3 Extra deployment options 
>> 
>>Problem: 
>>  In the 7th item of the bullet list, the following sentence: 
>> 
>>    Options MAY be processed in any order. 
>> 
>>  "MAY" is inappropriate in a list of requirements. 
>> 
>>To fix: 
>>  Use "may" instead of "MAY" and change the order of the 
>> sentences, 
>>  as follows: 
>> 
>>    Options MUST NOT require a specific order of processing.  Options 
>>    may be processed in any order. 
>> 
>>    
>>-fixed as advised.
>>
>>@ page 11 section 3.5 WS-DM Integration 
>> 
>>Problem: 
>>  The 2nd sentence of the 1sst paragraph says: 
>> 
>>    Both Portal and System endpoints support the MUWS ResourceId and 
>>    ManageabilityCapability attributes ... 
>> 
>>  It is unclear whether it is a requirement or not. 
>> 
>>To fix: 
>> 
>>  If it is a requirement, use "MUST", such as: 
>> 
>>    Both Portal and System endpoints MUST support ... 
>>
>>-fixed as advised.    
>>@ page 13 section 4.2.2 Portal Endpoint Operations 
>> 
>>Problem: 
>>  In the description of the "Create" operation, the following 
>> sentence: 
>> 
>>    hostname is OPTIONAL. 
>> 
>>  is inappropriate because the "OPTIONAL" in RFC2119 keyword means 
>> that 
>>  "an implementation can choose whether to implement the feature or 
>> not". 
>>  An optional parameter is not "OPTIONAL" in RFC2119's sense. 
>> 
>>To fix: 
>>  Change the sentence to: 
>> 
>>    hostname is optional. 
>> 
>>-fixed as advised. Also changed the text
>> in section 6.2.1 as advised above.
>>
>>
>>@ page 13 section 4.2.2 Portal Endpoint Operations 
>>here and also at 
>>page 15 section 4.3.2 System Endpoint Operations 
>> 
>>Problem: 
>>  Typo.  The operation name "GetResourceProperties" should be 
>> "GetResourceProperty". 
>> 
>>To fix: 
>>  Change "GetResourceProperties" to "GetResourceProperty". 
>> 
>>@ page 14 section 4.3.1 System Endpoint Properties 
>> 
>>-fixed as advised.
>>
>>Problem: 
>>  The "Meaning" column of the property "api:StartedTime" 
>> says "Time system was 
>>  *terminated*."  Is it intentional? 
>> 
>>To fix: 
>>  If the property indicates "started" time, say so. 
>> 
>>  BTW, when a system is "started"?  After receiving "Initialize" 
>> message, or 
>>  "Run" message, or otherwise?  The word "started" must 
>> also be clarified. 
>> 
>>-fixed by changing the sentence to "Time system moved into the running
>>state.". 
>> 
>>@ page 19 section 6.2.1 AddFile 
>> 
>>Problem: 
>>  In the AddFile operation, the word "schema" is used to indicate 
>> the first 
>>  part of the URL/URI (e.g. "http" in "http://www.example.com/";). 
>>  However, 
>>  RFCs defining URL/URI format (RFC1738 and RFC2396) uses the word 
>> "scheme" 
>>  for that part. 
>> 
>>To fix: 
>>  Change "schema" to "scheme". 
>> 
>>-fixed as advised. Updated the XSD document in the repository, and
>> in the appendix.
>>
>>@ page 22 section 6.2.7 Destroy 
>> 
>>Problem: 
>>  In the 2nd paragraph, "MAY NOT" is used.  However, in RFC2119, "MAY 
>> NOT" 
>>  is undefined and its use is confusing to the readers. 
>>  You may not use "MAY NOT". 
>> 
>>  In general, "MAY" means "allowed to do".  Negation of 
>> "MAY" ("MAY NOT") will 
>>  mean "not allowed (prohibited)" but such a sense is properly indicated 
>> by the 
>>  use of "MUST NOT".  If you want to say "allowed not to do", 
>> "need not" or 
>>  "not required to do" will work. 
>> 
>>  In this specific case, "MAY" is used to indicate *possibility*. 
>>  However, 
>>  "MAY" in RFC2119 only indicates *permission* to implementations. 
>>  In such a case lowercase "may" may be appropriate. 
>> 
>>To fix: 
>>  Change "as it MAY NOT be valid" to "as it may be 
>> invalid". 
>> 
>>-fixed as advised.
>>
>>[END] 
>>
>>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: draft-ggf-cddlm-deploy-api-hiro.doc
Type: application/msword
Size: 904192 bytes
Desc: not available
Url : http://www.ogf.org/pipermail/cddlm-wg/attachments/20060323/be146f09/attachment.doc 