Re: [netmod] example modules in 6087bis

[Ladislav Lhotka <[e-mail]>]

Benoit Claise <[e-mail]> writes:

> 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 think it is up to the document author to design the example module so
as to convey the idea that the example illustrates, and sometimes it's
best to use bare statements, and descriptions would really be just
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.
>>
>> 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.
>
>
>   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).
>

One option for automatic tools might be to parse module registrations in
IANA Considerations, and require --ietf compliance only for these
modules. Other modules demarcated with <CODE BEGINS/ENDS> would just
need to be plain valid, as you write.

Lada

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

-- 
Ladislav Lhotka, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67