Subject: [netmod] AD review of draft-ietf-netmod-yang-usage-05.txt

From: "Romascanu, Dan (Dan)" <[email-masked]>
Date: Tue, 22 Jun 2010 16:08:57 +0200

Here are my comments on draft-ietf-netmod-yang-usage-05.txt. These are
divided into Technical (marked T) and Editorial (marked E) comments. I
believe that one more revision of the document that addresses these
comments is necessary before proceeding to IETF Last Call. 

Thanks and Regards,

Dan

T1.  Running idnits results into the  following warning. 

     == Using lowercase 'not' together with uppercase 'MUST', 'SHALL',
'SHOULD',
     or 'RECOMMENDED' is not an accepted usage according to RFC 2119.
Please
     use uppercase 'NOT' together with RFC 2119 keywords (if that is
what you
     mean).
     
     Found 'MUST not' in this paragraph:
     
     Once a module name is published, it MUST not be reused, even if the
     RFC containing the module is reclassified to 'Historic' status.

T2. I would add to the second paragraph in the Introduction section a
phrase mentioning that while RFC 4181 was developped after more than one
decade of writing and deploying MIB modules, this document is issued
earlier in the YANG history, hence the hesitation of going directly to a
BCP, although from many aspects the document looks like a BCP document. 

T3. I suggest to add a phrase to the introduction about the target
audience - future YANG modules writers and reviewers. 

T4. Are there any exceptions that would justify using SHOULD rather than
MUST in 3.1? 

T5. Section 3.3 - 'These modules MUST be written in YANG' 

Do we really need a MUST here? The document is already about documents
that contain YANG modules, there is no need to repeat this. However, one
may imagine documents that combine for example YANG modules with MIB
modules - the MUST seems not to allow such a mix. 

T6. Sections 3.4 and 6 and Appendix A point 4 - we already have approved
security sections guidelines at
http://www.ops.ietf.org/netconf/yang-security-considerations.txt

T7. Section 3.5 - I suggest to add a phrase at the end of the section
mentioning that for cases when there are no IANA section RFC 5226 allows
to remove this section before the publication of the RFC> 

T8. Section 3.5.1 - s/a new YANG Namespace registry entry must be
requested from IANA/a new YANG Namespace registry entry MUST be
requested from IANA/

T9. Section 4.1 s/MUST not/MUST NOT/

T10. Need to add a normative reference to XPATH

T11. Section 4.7 - 'the document author contact information SHOULD be
present' - many documents have multiple authors, usually only the
contact information of one author is being included (at least with MIB
modules). 

T12. Section 4.8: Unless there is some good reason that I am missing:
s/It is desirable to include only valid YANG modules in documents/It is
RECOMMENDED to include only valid YANG modules in documents/

T13. Section 4.9: 

  There SHOULD only be one top-level data node defined in each YANG
   module.  However, there MAY be more than one if needed.

It would be good to describe an example of such a justified exception. 

T14. Section 4.10: 

   For string data types, if the length of the string is required to
   bounded in all implementations, then a length statement SHOULD be
   present.

s/SHOULD/MUST/ 

(or am I missing something?)

T15. Section 4.11: 

   If the type definition semantics are defined in an external document,
   then the reference statement SHOULD be present.

s/SHOULD/MUST/ 

(or am I missing something?)

T16. Same comment for the similar text in 4.12

17. Same comment for the similar text about operations in 4.13

18. Same content for the similar text about notifications semantics in
4.14

19. Appendix A, point 5 - is it really true that an IANA section will
always be present in a YANG module document? What about the case when we
just define a submodule? RFC 5226 allows not to include an IANA
Considerations section in an RFC if there are no IANA actions

20. Appendix A, point 9 - [ed.: online YANG validation tool URL TBD].
Should we rather consider here a pointer to a list of tools to be
maintained on the OPS Area Web pages (or wiki)? 

E1. The header of RFC 4181 is 'Guidelines for MIB documents'. Is there
any special reason not to use a similar header (like 'Guidelines for
YANG documents') for this document? 

E2. in section 2.1, second paragraph s/regarding YANG module
content/regarding YANG modules content/

E3. All over the document use consistently Internet-Draft rather than
Internet Draft. 

E4. in section 3.2 s/as MUST any special interpretations/as MUST be
noted any special interpretations/

E5. section 3.7 - provide a reference for the TLP. 

E6. section 4.2 - s/These includes/These include/

---

From: Andy Bierman <[email-masked]>
Date: Tue, 22 Jun 2010 08:13:51 -0700

> comments is necessary before proceeding to IETF Last Call. 

I will look at these comments in detail soon.
Some of your changes look like they will ignore
WG consensus (e.g., change SHOULD to MUST).

The reason this draft was written so early in the
process is that the YANG spec has minimum level
requirements that are not suitable for standardization.

I am actually surprised that the IESG approved YANG,
even though not 1 descriptive statement is
required in the entire document.  We went from
MUST have every DESCRIPTION clause in SMIv2,
to MAY have zero description-stmts in YANG.

> Dan

Andy

> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod
>
>

---

From: "Romascanu, Dan (Dan)" <[email-masked]>
Date: Tue, 22 Jun 2010 17:19:48 +0200

> -----Original Message-----
> From: Andy Bierman [mailto:[email-masked]] 

> Some of your changes look like they will ignore WG consensus 
> (e.g., change SHOULD to MUST).
> 

I assume that any change at this phase would challenge the WG consensus.
I am open to discussion on all suggested points. 

Dan

---

From: Phil Shafer <[email-masked]>
Date: Tue, 22 Jun 2010 11:30:45 -0400

>to MAY have zero description-stmts in YANG.

Fortunately IESG members lived thru those days too ;^)

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Tue, 22 Jun 2010 09:05:53 -0700

> Fortunately IESG members lived thru those days too ;^)

Except that you can't submit a YANG module to the
IETF that is missing a description stmt, so not sure
how this is really an improvement.  It is convenient
for software developers writing test modules that
are never intended to be published as part of
a distributed management system.

Andy

---

From: Andy Bierman <[email-masked]>
Date: Tue, 22 Jun 2010 09:50:47 -0700

no problems so far.... up to T5...
> ...

I changed the text as follows:

     This section contains the module(s) defined by the specification.
     These modules MUST be written using the YANG syntax defined in
     [I-D.ietf-netmod-yang].  A YIN syntax version of the module MAY
     also be present in the document.

I don't think we want WGs publishing YANG modules in YIN
syntax *instead* of YANG syntax.

Andy

---

From: Andy Bierman <[email-masked]>
Date: Tue, 22 Jun 2010 11:28:46 -0700

up to T15 now...

> (or am I missing something?)

There was lots of debate on this one.
The reason it is a SHOULD is that the
import-stmt for the module that defines the
external typedef MUST have a reference,
so this one may be redundant.

Do you still think s/SHOULD/MUST/ ?
Is an explanation sufficient?

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Wed, 23 Jun 2010 00:11:53 +0200 (CEST)

Hi Dan and Andy,

>    bounded in all implementations, then a length statement SHOULD be

There's a typo in this sentence, s/to bounded/to be bounded/

> Considerations section in an RFC if there are no IANA actions

Also submodules are registred in the IANA registry, so I believe all
these documents will have an IANA Considerations section.

Based on experience from the monitoring draft, should we also add that
references to all imported modules are listed in the text, as well as
all references from the 'reference' statement?  This is what we ended
up with in montoring:

   This YANG module imports typedefs from [YANG-TYPES] and references
   [RFC4741], [RFC4742], [RFC4743], [RFC4744], [RFC5539], [xmlschema-1],
   [YANG], [ISO/IEC 19757-2:2008], and [RFC5717].

I believe the RFC editor wants all references in text.

/martin

---

From: "Romascanu, Dan (Dan)" <[email-masked]>
Date: Wed, 23 Jun 2010 10:44:08 +0200

> Sent: Tuesday, June 22, 2010 7:51 PM
> To: Romascanu, Dan (Dan)
> Cc: NETMOD Working Group
> Subject: Re: [netmod] AD review of draft-ietf-netmod-yang-usage-05.txt
> 
> > that contain YANG modules, there is no need to repeat this. 
> However, 
> > one may imagine documents that combine for example YANG 
> modules with 
> > MIB modules - the MUST seems not to allow such a mix.
> >
> >   
> 

I think that you are partially missing the point I was trying to make.
Your observation about using YIN is fine, but there can be other data
models in the definition section not related to YANG or YIN (or
NETCONF). We would not prevent somebody to write a data model document
using say YANG and SMIv2 and we would like to apply the usage document
obviously only for the YANG DM. To cover this I suggest: 

      This section contains the module(s) defined by the specification.
      These modules MUST be written using the YANG syntax defined in
      [I-D.ietf-netmod-yang].  A YIN syntax version of the module or
data
      models expressed in other data modeling languages MAY also be 
      present in the document.

Dan

---

From: "Romascanu, Dan (Dan)" <[email-masked]>
Date: Wed, 23 Jun 2010 10:46:52 +0200

> Sent: Tuesday, June 22, 2010 9:29 PM
> To: Romascanu, Dan (Dan)
> Cc: NETMOD Working Group
> import-stmt for the module that defines the external typedef 
> MUST have a reference, so this one may be redundant.
> 

The explanation is sufficient. I agree with the WG consensus and rest my
case on this one. 

Thanks and Regards,

Dan

---

From: "Romascanu, Dan (Dan)" <[email-masked]>
Date: Wed, 23 Jun 2010 10:49:08 +0200

> From: Martin Bjorklund [mailto:[email-masked]] 
> Sent: Wednesday, June 23, 2010 1:12 AM
> To: Romascanu, Dan (Dan)
> Cc: [email-masked]
> > always be present in a YANG module document? What about the 
> case when 
> > we just define a submodule? RFC 5226 allows not to include an IANA 
> Also submodules are registred in the IANA registry, so I 
> believe all these documents will have an IANA Considerations section.

OK. 

> 
> 
> Based on experience from the monitoring draft, should we also 
> add that references to all imported modules are listed in the 
> text, as well as all references from the 'reference' 
> statement?  This is what we ended up with in montoring:
> 

Probably a SHOULD with an explanation of the rationale. 

Dan

---

From: Andy Bierman <[email-masked]>
Date: Wed, 23 Jun 2010 08:43:28 -0700

On 06/23/2010 01:44 AM, Romascanu, Dan (Dan) wrote:
>>> Do we really need a MUST here? The document is already 
>>>       
>> about documents 
>>     

I will add a sentence that says this document does not apply
to any module types other than YANG, which MAY also
exist in the document. 

Andy