Re: [netmod] example modules in 6087bis

[Martin Bjorklund <[e-mail]>]

Andy Bierman <[e-mail]> wrote:
> On Wed, Jan 18, 2017 at 9:12 AM, Benoit Claise <[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
> >
> > 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
> >
> > 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 inhttps://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 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

Fine with me.

> I prefer:
>    - MUST use CODE BEGINS for a real module
>    - MUST NOT use CODE BEGINS for an example module

I agree (see below)

>    - MUST pass pyang --ietf for a real module
>    - MUST pass pyang for example module

Yes, this follows from Benoit's proposed text above.

> 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.

I agree.



/martin


> 
> (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
> >
> >     o  http://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 [e-mail]://www.ietf.org/mailman/listinfo/netmod
> > .
> >
> >
> >
> >
> > _______________________________________________
> > netmod mailing list
> > [e-mail]
> > https://www.ietf.org/mailman/listinfo/netmod
> >
> >