[netmod] example modules in 6087bis
Martin Bjorklund <mbj@tail-f.com> Mon, 16 January 2017 15:48 UTC
Return-Path: <mbj@tail-f.com>
X-Original-To: netmod@ietfa.amsl.com
Delivered-To: netmod@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 3FA08129581 for <netmod@ietfa.amsl.com>; Mon, 16 Jan 2017 07:48:08 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -5.1
X-Spam-Level:
X-Spam-Status: No, score=-5.1 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RP_MATCHES_RCVD=-3.199, SPF_PASS=-0.001] autolearn=ham autolearn_force=no
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id VGfkp1oruyl0 for <netmod@ietfa.amsl.com>; Mon, 16 Jan 2017 07:48:06 -0800 (PST)
Received: from mail.tail-f.com (mail.tail-f.com [46.21.102.45]) by ietfa.amsl.com (Postfix) with ESMTP id A64D0129549 for <netmod@ietf.org>; Mon, 16 Jan 2017 07:48:06 -0800 (PST)
Received: from localhost (unknown [173.38.220.36]) by mail.tail-f.com (Postfix) with ESMTPSA id 0638F1AE047A for <netmod@ietf.org>; Mon, 16 Jan 2017 16:48:04 +0100 (CET)
Date: Mon, 16 Jan 2017 16:48:03 +0100
Message-Id: <20170116.164803.729427888661667991.mbj@tail-f.com>
To: netmod@ietf.org
From: Martin Bjorklund <mbj@tail-f.com>
X-Mailer: Mew version 6.7 on Emacs 24.5 / Mule 6.0 (HANACHIRUSATO)
Mime-Version: 1.0
Content-Type: Text/Plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/GGLXJ8edgiKL0RUOYRcM2ATZIJc>
Subject: [netmod] example modules in 6087bis
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.17
Precedence: list
List-Id: NETMOD WG list <netmod.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/netmod>, <mailto:netmod-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/netmod/>
List-Post: <mailto:netmod@ietf.org>
List-Help: <mailto:netmod-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/netmod>, <mailto:netmod-request@ietf.org?subject=subscribe>
X-List-Received-Date: Mon, 16 Jan 2017 15:48:08 -0000
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" 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. 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. /martin
- [netmod] example modules in 6087bis Martin Bjorklund
- Re: [netmod] example modules in 6087bis Andy Bierman
- Re: [netmod] example modules in 6087bis Martin Bjorklund
- Re: [netmod] example modules in 6087bis Benoit Claise
- Re: [netmod] example modules in 6087bis Andy Bierman
- Re: [netmod] example modules in 6087bis Martin Bjorklund
- Re: [netmod] example modules in 6087bis Ladislav Lhotka
- Re: [netmod] example modules in 6087bis Benoit Claise
- Re: [netmod] example modules in 6087bis Kent Watsen
- Re: [netmod] example modules in 6087bis Martin Bjorklund
- Re: [netmod] example modules in 6087bis Andy Bierman
- Re: [netmod] example modules in 6087bis Kent Watsen
- Re: [netmod] example modules in 6087bis Benoit Claise
- Re: [netmod] example modules in 6087bis Martin Bjorklund
- Re: [netmod] example modules in 6087bis Mahesh Jethanandani
- Re: [netmod] example modules in 6087bis-10 t.petch