On Mon, Jan 16, 2017 at 7:48 AM, Martin Bjorklund <[email protected]> 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 > [email protected] > https://www.ietf.org/mailman/listinfo/netmod >
_______________________________________________ netmod mailing list [email protected] https://www.ietf.org/mailman/listinfo/netmod
