Subject: Re: [netmod] Broadband Forum questions on RFC 6087bis

From: William Lupton <[email-masked]>
Date: Wed, 20 Jan 2016 14:45:34 +0000

All,

I didn't see any follow-up to these questions / comments. Any thoughts? 

Thanks,
William

> On 11 Dec 2015, at 12:54, William Lupton <[email-masked]> wrote:
> 
> All,
> 
> Here are some questions / comments from the Broadband Forum on RFC 6087bis-05.
> 
> Thanks,
> William
> 
> --------
> 
> 1. Potentially confusing use of the term "prefix"
> 
> Section 5.1 (Module Naming Conventions) talks about prefixes but in this context means "strings at the beginning of module names" rather than YANG prefixes that are the topic of Section 5.2. This could (and did!) cause confusion.
> 
> 
> 2. Rules re changing submodule names
> 
> Section 5.7 (Lifecycle Management) says that "The [...] submodule name MUST NOT be changed, once the document containing the module or submodule is published" but this might contradict RFC 6020 Section 11, which says "A module may be split into a set of submodules, or a submodule may be removed...".
> 
> More specifically, 6020 doesn't mention renaming a submodule (so presumably that's not permitted), but the mention of both splitting modules into submodules AND removing submodules suggests that arbitrary module/submodule refactoring is permitted. And if I'm being pedantic, revision #1 could have submodule A1, revision #2 could remove it, and revision #3 could reintroduce it as submodule A2, so that's effectively a rename!
> 
> 
> 3. References to RPCs need also to mention actions
> 
> In most (or all?) places that RPCs are mentioned, presumably actions need to be mentioned?
> 
> 
> 4. Implications of adding defaults
> 
> Section 5.12 (Reusable Type Definitions) says that "If an appropriate default value can be associated with the desired semantics, then a default statement SHOULD be present". Is it correct that adding a default effectively adds a MANDATORY requirement for a server to support the default value for that node, and therefore to support the concept modelled by the node (albeit only with the default behaviour)? Whereas if there were no default then there would be no requirement at all to support the concept modelled by that node? If so, then adding a default seems like something that shouldn't be done lightly... or am I making too much of this?
> 
> 
> 5. Guidance re YANG features
> 
> 6087 doesn't always refer to features consistently. For example Section 5.5 (Conditional Statements) says "If a data definition is optional, depending on server support for a NETCONF protocol capability, then a YANG 'feature' statement SHOULD be defined" (which seems to tie the "feature" concept to NETCONF protocol capabilities), whereas Section 5.17 (Feature Definitions) says "The YANG "feature" statement is used to define a label for a set of optional functionality within a module". The latter description seems more in keeping with the spirit of 6020, so perhaps the former text could be adjusted to align with it?
> 
> 
> 6. Guidance re YANG deviations
> 
> The 6020 discussion of deviations is mostly about implementing LESS rather than MORE. Obviously the deviate statement's "add" argument is described (and there is an example) but there seems to be no discussion that use of deviate with "add" might be a GOOD thing.
> 
> The 6087 discussion of deviations says that they can be useful for documenting server capabilities but again the emphasis seems to be on documenting implementing LESS rather than MORE.
> 
> The result seems to be that deviations have a bad name. If indeed there are accepted good uses of deviations then it would be good if this was made clearer, both in 6020 and in 6087.

---

From: Andy Bierman <[email-masked]>
Date: Thu, 21 Jan 2016 16:18:35 -0800

On Wed, Jan 20, 2016 at 6:45 AM, William Lupton <[email-masked]
> wrote:

> > Section 5.1 (Module Naming Conventions) talks about prefixes but in this
> context means "strings at the beginning of module names" rather than YANG
> prefixes that are the topic of Section 5.2. This could (and did!) cause
> confusion.
> >
>

I will change the text so the term prefix is not used

> > Section 5.7 (Lifecycle Management) says that "The [...] submodule name
> MUST NOT be changed, once the document containing the module or submodule
> is published" but this might contradict RFC 6020 Section 11, which says "A
> module may be split into a set of submodules, or a submodule may be
> removed...".
> >
> > More specifically, 6020 doesn't mention renaming a submodule (so
> presumably that's not permitted), but the mention of both splitting modules
> into submodules AND removing submodules suggests that arbitrary
> module/submodule refactoring is permitted. And if I'm being pedantic,
> revision #1 could have submodule A1, revision #2 could remove it, and
> revision #3 could reintroduce it as submodule A2, so that's effectively a
> rename!
> >
>

I do not see any issue here.
Moving an object does not change the submodule name.

The main module is required in YANG 1.1  to include all its submodules to
emphasize
that they are not hierarchical and they do not have any sort
of "sub-namespace" property.

> > In most (or all?) places that RPCs are mentioned, presumably actions

I will check that

> > Section 5.12 (Reusable Type Definitions) says that "If an appropriate
> default value can be associated with the desired semantics, then a default
> statement SHOULD be present". Is it correct that adding a default
> effectively adds a MANDATORY requirement for a server to support the
> default value for that node, and therefore to support the concept modelled
> by the node (albeit only with the default behaviour)? Whereas if there were
> no default then there would be no requirement at all to support the concept
> modelled by that node? If so, then adding a default seems like something
> that shouldn't be done lightly... or am I making too much of this?
> >
>

Yes it adds a mandatory implementation requirement for the new revision.
This is no different than any change to a module, like restricting the
range of an integer.

> > 6087 doesn't always refer to features consistently. For example Section
> 5.5 (Conditional Statements) says "If a data definition is optional,
> depending on server support for a NETCONF protocol capability, then a YANG
> 'feature' statement SHOULD be defined" (which seems to tie the "feature"
> concept to NETCONF protocol capabilities), whereas Section 5.17 (Feature
> Definitions) says "The YANG "feature" statement is used to define a label
> for a set of optional functionality within a module". The latter
> description seems more in keeping with the spirit of 6020, so perhaps the
> former text could be adjusted to align with it?
>

OK -- the SHOULD text will be removed

> > The 6020 discussion of deviations is mostly about implementing LESS
> rather than MORE. Obviously the deviate statement's "add" argument is
> described (and there is an example) but there seems to be no discussion
> that use of deviate with "add" might be a GOOD thing.
> >
> > The 6087 discussion of deviations says that they can be useful for
> documenting server capabilities but again the emphasis seems to be on
> documenting implementing LESS rather than MORE.
> >
> > The result seems to be that deviations have a bad name. If indeed there
> are accepted good uses of deviations then it would be good if this was made
> clearer, both in 6020 and in 6087.
>
>

I don't agree this is a good idea.
Adding sub-statements can damage interoperability just the same as
taking things away.  E.g., add a must-stmt to a leaf that the client doesn't
know about.

Andy

> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod
>

---

From: William Lupton <[email-masked]>
Date: Fri, 22 Jan 2016 14:33:32 +0000

Thanks for the responses. One clarification below on what is definitely a minor point!

> On 22 Jan 2016, at 00:18, Andy Bierman <[email-masked]> wrote:
> On Wed, Jan 20, 2016 at 6:45 AM, William Lupton <[email-masked] <mailto:[email-masked]>> wrote:

My point was to question why renaming submodules is forbidden when in fact it seems that submodule rename can be achieved via other means. It's not that I actually want to do it, just that 6087 and 6020 don't seem quite consistent on this topic.

William

---

From: Andy Bierman <[email-masked]>
Date: Fri, 22 Jan 2016 08:38:08 -0800

Hi,

The changed submodule name looks like
a new name and the old submodule was deleted.
How does a tool determine it is some old submodule
but the name was changed?

Andy

On Fri, Jan 22, 2016 at 6:33 AM, William Lupton <[email-masked]

> On Wed, Jan 20, 2016 at 6:45 AM, William Lupton <
> [email-masked]> wrote:
>>
> My point was to question why renaming submodules is forbidden when in fact
> it seems that submodule rename can be achieved via other means. It's not
> that I actually want to do it, just that 6087 and 6020 don't seem quite
> consistent on this topic.
>
> William
>

---

From: William Lupton <[email-masked]>
Date: Fri, 22 Jan 2016 17:16:20 +0000

It probably wouldn't (unless the tool implements an algorithm similar to the Git algorithm that detects "move" rather than "delete" + "add"). But given that you could delete it in one revision and then add it back with a different name in a subsequent revision should it really be forbidden? As I said... a minor point! W.

> On 22 Jan 2016, at 16:38, Andy Bierman <[email-masked]> wrote:
> 
> Hi,
> 
> On Fri, Jan 22, 2016 at 6:33 AM, William Lupton <[email-masked] <mailto:[email-masked]>> wrote:
>> On 22 Jan 2016, at 00:18, Andy Bierman <[email-masked] <mailto:[email-masked]>> wrote:

---

From: Andy Bierman <[email-masked]>
Date: Fri, 22 Jan 2016 09:39:19 -0800

Hi,

I never liked submodules. IMO just more IETF over-engineering.
They have always confused customers into thinking they
are just modules within modules. Wrong.  They merely partition YANG
modules into multiple syntactic bundles.  There is only 1 module namespace.

Actually I think it doesn't matter if the submodule name changes, so I
should
remove the text in question.  One can remove all the submodules from
rev N to N+1 if they want, and add different names back (as you pointed
out).
If it doesn't change the module namespace contents it's OK.

Andy

On Fri, Jan 22, 2016 at 9:16 AM, William Lupton <[email-masked]

> It probably wouldn't (unless the tool implements an algorithm similar to
> the Git algorithm that detects "move" rather than "delete" + "add"). But
> given that you could delete it in one revision and then add it back with a
> different name in a subsequent revision should it really be forbidden? As I
> said... a minor point! W.
>
> On Fri, Jan 22, 2016 at 6:33 AM, William Lupton <
>> My point was to question why renaming submodules is forbidden when in
>> fact it seems that submodule rename can be achieved via other means. It's
>> not that I actually want to do it, just that 6087 and 6020 don't seem quite