Re: [netmod] example modules in 6087bis

[Martin Bjorklund <[e-mail]>]

Kent Watsen <[e-mail]> wrote:
> Hi Andy,
> 
> I think this discussion has come to a head.  Please submit an updated 6087bis as soon as you can.  Some comments:
> 
> 
> 1) on the 3rd line below, should the text clarify that --ietf is only for IETF modules?  Also, how does the MUST here jive with the SHOULD in Section 4.10?
> 
>    - 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
> 
> 
> 2) related to #1, Section 5 says "In general, modules in IETF Standards Track specifications MUST comply with all syntactic and semantic requirements of YANG [RFC7950]."
> 
>    First, what does "In general...MUST" mean?  - maybe the 
>    sentence should start with "Modules in IETF..."?
> 
>    Second, can we add a statement for non-IETF SDOs that might
>    have other conventions/restrictions?  Would we recommend
>    --strict for starters, until they can add an SDO-specific
>    flag (e.g., --<sdo>) to pyang?

We wouldn't talk about any specific tool; we'd just talk about
compliance with this document.  Other SDOs will have to decide on
their own rules, but we can suggest that they use all our rules except
the naming convention for modules and namespaces.


> 3) The first paragraph in Section 4.6 isn't clear, how about this?
> 
>  OLD
>    This section contains the module(s) defined by the specification.
>    These modules SHOULD be written using the YANG syntax defined in
>    [RFC7950].  YANG 1.0 [RFC6020] MAY be used if no YANG 1.1 constructs
>    or semantics are needed in the module.
> 
>  NEW
>    This section contains the module(s) defined by the YANG specification.
>    These modules SHOULD be written using the YANG 1.1 [RFC7950] syntax;
>    YANG 1.0 [RFC6020] syntax MAY be used if no YANG 1.1 constructs
>    or semantics are needed in the module.
> 
>  Note: this reads better, but I wonder, since YANG 1.0 syntax is a
>  subset of YANG 1.1 syntax, what is really being said here? - that
>  yang-version statement is optional?  Or maybe, instead of focusing
>  on syntax, the statement should regard the version of YANG used?

The point is that yang-version 1.1 SHOULD be used, and yang-version 1
MAY be used.

> 4) Lastly, picking up on this discussion:
> 
>      https://www.ietf.org/mail-archive/web/netmod/current/msg17277.html.
> 
>    can add an Informational reference to RFC 4151 in Section 5.9?
>    Maybe something like this:
> 
>  OLD
> 
>    The following examples are for non-Standards-Track modules.  The
>    domain "example.com" SHOULD be used in all namespace URIs for example
>    modules.
> 
>        http://example.com/ns/example-interfaces
> 
>        http://example.com/ns/example-system
> 
>  NEW
> 
>    The following URIs exemplify what might be used by non Standards
>    Track modules.  Note that the domain "example.com" SHOULD be used
>    by example modules in IETF drafts.
> 
>    Example URIs using URLs per RFC 3986 [RFC3986]:
> 
>        http://example.com/ns/example-interfaces
>        http://example.com/ns/example-system
> 
>    Example URIs using tags per RFC 4151 [RFC4151]:
>  
>        tag:example.com,2017:example-interfaces
>        tag:example.com,2017:example-system

I would like to see urn:example:<module-name>, that's what I usually
use here.


/martin