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@ggf.org [mailto:owner-cddlm-wg@ggf.org] On Behalf Of Steve Loughran Sent: Wednesday, March 15, 2006 7:42 AM To: 'cddlm-wg@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]