Re: [netmod] example modules in 6087bis

[Benoit Claise <[e-mail]>]

On 1/18/2017 7:00 PM, Andy Bierman wrote:
>
>
> On Wed, Jan 18, 2017 at 9:12 AM, Benoit Claise <[e-mail] 
> <mailto:[e-mail]>> wrote:
>
>     Martin,
>>     Hi,
>>
>>     It turns out that the recommendations on example modules are a bit
>>     unclear.  Different drafts do very different things.  Some examples:
>>
>>     https://tools.ietf.org/html/draft-ietf-i2rs-yang-l3-topology-08#section-6.1.2
>>     <https://tools.ietf.org/html/draft-ietf-i2rs-yang-l3-topology-08#section-6.1.2>
>>
>>     This example module really looks like a real module.  It uses an
>>     IANA-controlled namespace, and the meta-statements indicate that this
>>     is a normative modules.  But the module does not use the <CODE> tags.
>>
>>
>>     https://tools.ietf.org/html/draft-ietf-netconf-restconf-18#appendix-C.1
>>     <https://tools.ietf.org/html/draft-ietf-netconf-restconf-18#appendix-C.1>
>>
>>     This module is better, but it is written to follow RFC 6087 rules
>>     (pass pyang --ietf), with the result that it contains a bit of "noise"
>     It takes a lot of YANG experience to be able to distinguish what
>     is noise or not. 
>
> I agree.  I see Martin's point though -- maintenance clauses like 
> contact and organization
> are not really needed for examples.
>
>>     with some meaningless descriptions and meta-statements.  It also does
>>     not use <CODE> tags.
>>
>>
>>     A good example (IMO) is found in
>>     https://tools.ietf.org/html/rfc8022#appendix-C
>>     <https://tools.ietf.org/html/rfc8022#appendix-C>
>>
>>     It uses descriptions when necessary (high s/n), no fake
>>     meta-statements etc.
>>
>>     However, it might be a good idea to require example modules to have a
>>     "description" statement that explains what the module examplifies.
>>     For example, the example-rip could have:
>>
>>        description
>>          "This example module demonstrates how the core routing data model
>>           can be extended to support a new control-plane protocol.  It is
>>           intended as an illustration rather than a real definition of a
>>           data model for the Routing Information Protocol (RIP).";
>>
>>
>>
>>     I think that 6087bis is clear when it says:
>>
>>        The guidelines in this document refer mainly to a normative complete
>>        module or submodule, but may be applicable to example modules and
>>        YANG fragments as well.
>>
>>     I think this states that example modules do not have to pass pyang
>>     --ietf.
>>
>>
>>     In order to make this more clear, I suggest the following changes to
>>     draft-ietf-netmod-rfc6087bis-09
>>
>>     In the Terminology section 2.4:
>>
>>     NEW:
>>
>>        o  Example module:  A complete YANG module or submodule that is
>>           intended to illustrate some specific aspect, but not intended for
>>           actual use.
>     It doesn't solve this issue, because
>     https://tools.ietf.org/html/draft-ietf-netmod-rfc6087bis-09#section-4.2.1
>     <https://tools.ietf.org/html/draft-ietf-netmod-rfc6087bis-09#section-4.2.1>
>     says:
>
>           The <CODE BEGINS> convention SHOULD be used for complete example
>           modules, but not YANG fragments.
>
>     That implies to me that we have 3 types: 1. _complete _example
>     modules => I read it that they must pass pyang -ietf, SHOULD have
>     <CODE BEGINS>     If there is <CODE BEGINS>, it's because people
>     will want to extract it, and play with it. So the tools chain must
>     work 2. the other example modules. No <CODE BEGINS>. I guess they
>     don't pass pyang 3. YANG fragments. No <CODE BEGINS>. I guess they
>     don't pass pyang In practice, 2 and 3 are the same. So we need
>     just two definition Scrap "complete" would help but that's not
>     enough:
>
>       The <CODE BEGINS> convention SHOULD be used for example
>       modules, but not YANG fragments.
>
>     We only need to clarify 3 points     <CODE BEGINS>, yes/no    
>     pyang, yes/no     pyang --ietf yes/no I guess we want, putting all
>     this together:
>
>        o  Example module:  A complete YANG module or submodule that is
>           intended to illustrate some specific aspect, but not intended for
>           actual use. Example module MUST be valid according to RFC 7950,
>           except when they are used to illustrate some illegal constructs.
>           Example module MAY be valid according to the rules in this document.
>
>        o  YANG fragment:  A incomplete YANG module or submodule that is
>           intended to illustrate some specific aspect, but not intended for
>           actual use. YANG fragments MUST be valid according to RFC 7950,
>           except when they are used to illustrate some illegal constructs.
>
> This is good
> I prefer:
>    - MUST use CODE BEGINS for a real module
>    - MUST NOT use CODE BEGINS for an example module
>    - MUST pass pyang --ietf for a real module
>    - MUST pass pyang for example module
Fine with me. Consistency is key here. Is it time to conclude this 
discussion? Regards, Benoit
> I have already received private emails about implementing the 
> example-jukebox
> module in RESTCONF as part of the standard.  We already have operational
> experience that people can be confused by the example modules, and
> think they are supposed to be implemented for RFC compliance.
>
>       The <CODE BEGINS> convention SHOULD be used for example
>       modules that pass validation according to RFC 7950.
>
>       The <CODE BEGINS> convention MUST NOT be used for YANG fragment
>       and for example modules that are used to illustrate some illegal constructs
>       (therefore failing validation according to RFC 7950).
>
> This text concerns me a little
> We are not following the <CODE BEGINS> anywhere for examples.
> the tools are extracting anything that starts "module blah".
> IMO this makes it easier to confuse real and example modules.
> I would prefer to consider only real modules as Code Components.
> (We collect broken modules to test the compiler in modules/test/fail 
> folder,
> so even bad modules might be extracted.)
>
>>     In section 4:
>>
>>     NEW:
>>
>>         All normative modules or submodules, example modules or submodules,
>>         and example YANG fragments MUST be valid according to RFC 7950,
>>         except when they are used to illustrate some illegal constructs.
>     We wouldn't need this if you take my proposal
>>     In Section 4.2.1 "Example Modules":
>>
>>     NEW:
>>
>>        An example module SHOULD have a namespace on the form
>>
>>          ohttp://example.com/<module-name> OR
>>          o  urn:example:<module-name>
>>
>>        An example module SHOULD have a description statement that describes
>>        that it is an example module, and what it examplifies.
>>
>>        An example module SHOULD NOT have any additional meta-statements
>>        (i.e., "organization", "contact", or "reference").
>>
>>        An example module SHOULD use the "description" statement in any
>>        definition where it is required to understand the example.
>>
>     Fine. Note that the RESTCONF RFC publication depends on this
>     RFC6087bis convention. So let's quickly come to a conclusion.
>     Regards, Benoit
>
> Andy
>
>>     /martin
>>
>>     _______________________________________________
>>     netmod mailing list
>>     [e-mail] <mailto:[e-mail]>
>>     https://www.ietf.org/mailman/listinfo/netmod
>>     <https://www.ietf.org/mailman/listinfo/netmod>
>>     .
>>
>     _______________________________________________ netmod mailing
>     list [e-mail] <mailto:[e-mail]>
>     https://www.ietf.org/mailman/listinfo/netmod
>     <https://www.ietf.org/mailman/listinfo/netmod> 
>