Re: [netmod] example modules in 6087bis

On Mon, Jan 16, 2017 at 7:48 AM, Martin Bjorklund <mbj@tail-f.com> 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

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

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

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)

>
> 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
> netmod@ietf.org
> https://www.ietf.org/mailman/listinfo/netmod
>