On 1/18/2017 7:00 PM, Andy Bierman wrote:
On Wed, Jan 18, 2017 at 9:12 AM, Benoit Claise <[email protected]
<mailto:[email protected]>> 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
[email protected] <mailto:[email protected]>
https://www.ietf.org/mailman/listinfo/netmod
<https://www.ietf.org/mailman/listinfo/netmod>
.
_______________________________________________ netmod mailing
list [email protected] <mailto:[email protected]>
https://www.ietf.org/mailman/listinfo/netmod
<https://www.ietf.org/mailman/listinfo/netmod>
_______________________________________________
netmod mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
