Re: [netmod] example modules in 6087bis

[Martin Bjorklund <[e-mail]>]

Andy Bierman <[e-mail]> wrote:
> On Mon, Jan 16, 2017 at 7:48 AM, Martin Bjorklund <[e-mail]> wrote:
> 
> > 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.
> >
> >
> 
> This example needs to be redone.
> 
> There are 2 conflicting goals that need to be addressed.
> 
> 1) Clearly identify a module as an example; not meant to be implemented;
>     only present to demonstrate protocol interactions with an example module

Yes - maybe add this text to 6087bis?

> 2) Teach people good YANG authoring habits
>      Way too much cut-and-paste out there so maybe if the examples
>      follow "pyang --ietf" people will learn the right way to construct a
> module

This assumes that people copy&paste from example modules.  I'm not
sure that this a real problem.  If they do that when they develop IETF
modules, Benoit's script will kick in anyway.

> > 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"
> > 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
> >
> > It uses descriptions when necessary (high s/n), no fake
> > meta-statements etc.
> >
> >
> 
> 
> It does not have a revision-stmt, which is really important
> for real YANG modules.

Yes, but it is not important for examples (typically).

> IMO the random set of description-stmts is no better or worse
> than the examples in the RESTCONF draft.
> 
> 
> 
> > 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).";
> >
> >
> >
> OK
> 
> 
> >
> > 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.
> >
> >
> 
> I agree that examples do not need to pass with the --ietf flag.
> But is the guideline a SHOULD pass or MAY pass?
> (agree it is not MUST pass)

The current text implies MAY.  Perhaps s/may/MAY/ in the original text
in order to make this clear?


/martin


> > 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.
> >
> >
> > 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.
> >
> >
> > 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.
> >
> >
> >
> 
> new text is OK with me.
> I would make it clear that module description and revision
> SHOULD be present. All other optional clauses MAY be present.
> 
> 
> 
> >
> >
> > /martin
> >
> >
> Andy
> 
> 
> > _______________________________________________
> > netmod mailing list
> > [e-mail]
> > https://www.ietf.org/mailman/listinfo/netmod
> >