Subject: [Netmod-ver-dt] Comments on clacla draft

From: Robert Wilton <[email-masked]>
Date: Mon, 26 Nov 2018 12:12:26 +0000

Hi,

I've read the clacla draft, and these are some comments for discussion, 
on the presumption that the DT is going to use this draft as a basis for 
some of the solution.

1) As Juergen suggests after the introduction I think that we should 
explicitly list the sections that may end up modify YANG's behaviour, 
e.g. by updating RFC 7950.

1 ii) I think that the draft should explicitly state which requirements 
it addresses, and which is does not address.  I'm presuming that this 
draft, at least at this stage, should try and address everything except 
2.2, 3.1? and 3.2.

2) Section 2.1: Semantic Versioning
- Use modified semver (probably we need a better name for this), perhaps 
"YANG semver".
- Document the rules for modified semver.

2 ii) I think that we should think about removing sections 2.1.2 and 
2.1.3 on "Derived Semantic Version".  I think that this text should 
eventually end up as part of a tooling based schema comparison draft.  
Perhaps we could create a separate clone of the draft on github to hold 
the text that we are saving for later.

2 iii) I think that we should provide a section on guidelines on how 
Semver should be used (perhaps updating RFC 8407 and 7950 section 11).  
This would (at least partially) address requirement 5.1, "The solution 
MUST provide guidance to model authors and clients on how to use the new 
YANG versioning scheme."

3) Section 2.2:  Import by Semantic Version
  - I think that this is broadly on the right track, but the scheme does 
seem a bit complicated.  Hence I wonder whether there is any scope to 
simplify this at all.  Probably it would be good to allocate some of the 
DT meeting time to discuss this.

E.g. I was wondering if we build this using the following primitives:
- For clarify, always matching on three fields <major>.<min>.<patch>.
- For each field:
    "*" means any value is acceptable. Can't be used where a more 
specific min/patch is being used (E.g. "*.1-2.*") is not allowed.
   "X+" means any value matching X or greater.
   "X-Y" means any value inclusively in the range X to Y.
  - So rather than "[1.0.0-3.0.0)", this would become "1-2.*.*"
- Perhaps allow multiple import-version statements.  All should be 
evaluated, and the most recent version of those matching the pattern is 
selected for import.  So "[1.5-2.0.0),[2.5" would be two statements 
"1.5+.*" and "2.5.*"

4) Section 2.3: Updates to YANG 1.1 Module Update Rules
This text might be better more tightly co-located with section 2.1 on 
semantic versioning.

5) Section 2.4: Updates to ietf-yang-library
  - We should also augment module-set/import-only-module with the 
version as well.
  - I suggest changing the type of "deprecated-nodes-present" to 
"empty".  If present, then it has the semantics currently described.  If 
not present, then the behaviour is undefined (as per RFC 7950).
- Similarly, I suggest changing the name and type of 
"obsolete-nodes-present" to "obsolete-nodes-absent" of type "empty".  If 
present, then it has the semantics that are currently described.  If not 
present, then the behaviour is undefined (as per RFC 7950).

6) I think that this draft should also address requirements 5.2 and 5.3.

        5.2  The solution is REQUIRED to describe how to transition from
             the existing YANG 1.0/1.1 versioning scheme to the new
             scheme.

        5.3  The solution MUST describe how the versioning scheme affects
             the interpretation of instance data and references to
             instance data, for which the schema definition has been
             updated in a non-backwards-compatible way.

Thanks,
Rob

---

From: Balázs Lengyel <[email-masked]>
Date: Mon, 26 Nov 2018 12:35:20 +0000

Agree mostly. See below. Joe how
should we proceed with the edits?

regards Balazs

On 2018. 11. 26. 13:12, Robert Wilton
wrote:

Hi,

I've read the clacla draft, and these are some comments for
discussion, on the presumption that the DT is going to use this
draft as a basis for some of the solution.

1) As Juergen suggests after the introduction I think that we
should explicitly list the sections that may end up modify
YANG's behaviour, e.g. by updating RFC 7950.

BALAZS: OK

1 ii) I think that the draft should explicitly state which
requirements it addresses, and which is does not address.  I'm
presuming that this draft, at least at this stage, should try
and address everything except 2.2, 3.1? and 3.2.

BALAZS: This is already included in chapter 1,
but needs updates. 3.3 is a client requirement, so the solution
should mention it, but not provide a solution.

- Use modified semver (probably we need a better name for this),
perhaps "YANG semver".

BALAZS: OK

2 ii) I think that we should think about removing sections
2.1.2 and 2.1.3 on "Derived Semantic Version".  I think that
this text should eventually end up as part of a tooling based
schema comparison draft.  Perhaps we could create a separate
clone of the draft on github to hold the text that we are saving
for later.

BALAZS: We need to say something about YAMs
that do not include Yang semver. Minimum: If semver is missing NBC
should be assumed. Otherwise agree.

2 iii) I think that we should provide a section on guidelines
on how Semver should be used (perhaps updating RFC 8407 and 7950
section 11).  This would (at least partially) address
requirement 5.1, "The solution MUST provide guidance to model
authors and clients on how to use the new YANG versioning
scheme."

- I think that this is broadly on the right track, but the
scheme does seem a bit complicated.  Hence I wonder whether
there is any scope to simplify this at all.  Probably it would
be good to allocate some of the DT meeting time to discuss this.

E.g. I was wondering if we build this using the following
primitives:

- For clarify, always matching on three fields
<major>.<min>.<patch>.

- For each field:

"*" means any value is acceptable. Can't be used where a more
specific min/patch is being used (E.g. "*.1-2.*") is not
allowed.

- Perhaps allow multiple import-version statements.  All should
be evaluated, and the most recent version of those matching the
pattern is selected for import.  So "[1.5-2.0.0),[2.5" would be
two statements "1.5+.*" and "2.5.*"

This text might be better more tightly co-located with section
2.1 on semantic versioning.

BALAZS: I would lift this out to a top level
chapter covering all sub-proposals.

- I suggest changing the type of "deprecated-nodes-present" to
"empty".  If present, then it has the semantics currently
described.  If not present, then the behaviour is undefined (as
per RFC 7950).

- Similarly, I suggest changing the name and type of
"obsolete-nodes-present" to "obsolete-nodes-absent" of type
"empty".  If present, then it has the semantics that are
currently described.  If not present, then the behaviour is
undefined (as per RFC 7950).

BALAZS: I personally completely hate the empty
type. I prefer explicit data.

6) I think that this draft should also address requirements 5.2
and 5.3.

Thanks,

Rob

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

--
Balazs Lengyel Ericsson Hungary Ltd.
Senior Specialist
Mobile: +36-70-330-7909 email: [email-masked]

---

From: Joe Clarke <[email-masked]>
Date: Mon, 26 Nov 2018 08:59:08 -0500

On 11/26/18 07:35, Balázs Lengyel wrote:
> Agree mostly. See below. Joe how should we proceed with the edits?

First thing is to rename the draft and structure it as a DT document.
That's the easy part.  I can do that today.

Second is to start to reshape it.  I have some other tasks I need to get
to, so I can't commit to doing that this week, though I may be able to
start on it.  That said, I think the work can be divided and perhaps
multiple people can take a section for updating.

>> e.g. by updating RFC 7950.

Agreed.  This sounds reasonable.

>> presuming that this draft, at least at this stage, should try and
>> address everything except 2.2, 3.1? and 3.2.
>>
> BALAZS: This is already included in chapter 1, but needs updates. 3.3 is
> a client requirement, so the solution should mention it, but not provide
> a solution.

Yep.  We did this as the last major edit to the clacla draft.  But it is
out of date with the current requirement list.

>> - Use modified semver (probably we need a better name for this),

I like this designation.

>> - Document the rules for modified semver.

++

>> Perhaps we could create a separate clone of the draft on github to
>> hold the text that we are saving for later.

Either that or an issue to track these items.

>>
> BALAZS: We need to say something about YAMs that do not include Yang
> semver. Minimum: If semver is missing NBC should be assumed. Otherwise
> agree.

While one should assume 7950#11 rules, in practice we know that won't be
the case with vendor modules.  This is why we have the derived-semver to
begin with.  Officially, we could state that in the absence of YANG
semver, one should assume 7950#11 rules, but be aware that some modules
incorporate NBC changes nonetheless.  Eventually, we can point to more
tooling options to identify potential NBC pitfalls.

>> Semver should be used (perhaps updating RFC 8407 and 7950 section
>> 11).  This would (at least partially) address requirement 5.1, "The
>> solution MUST provide guidance to model authors and clients on how to
>> use the new YANG versioning scheme."
>>
>>  - I think that this is broadly on the right track, but the scheme
>> does seem a bit complicated.  Hence I wonder whether there is any
>> scope to simplify this at all.  Probably it would be good to allocate
>> some of the DT meeting time to discuss this.

Yes.  We went complex to try and satisfy non-linear version increments
and be as flexible as possible.  In practice, it is probably sufficient
to allow for imports within a major version.  But we need to figure out
a way to deal with m|M.

>> evaluated, and the most recent version of those matching the pattern
>> is selected for import.  So "[1.5-2.0.0),[2.5" would be two statements
>> "1.5+.*" and "2.5.*"
>>
>>
> BALAZS: I would lift this out to a top level chapter covering all
> sub-proposals.

As was mentioned above we can cover those sections that update 7950
towards the beginning.  I don't think we want to address all potential
solutions in this draft, though.

>> "empty".  If present, then it has the semantics currently described. 
>> If not present, then the behaviour is undefined (as per RFC 7950).
>> "obsolete-nodes-present" to "obsolete-nodes-absent" of type "empty". 
>> If present, then it has the semantics that are currently described. 
>> If not present, then the behaviour is undefined (as per RFC 7950).
>>
> BALAZS: I personally completely hate the empty type. I prefer explicit data.

So do I.

>>             updated in a non-backwards-compatible way.

Sure, but we need more discussion on the how here.

Joe

---

From: Robert Wilton <[email-masked]>
Date: Mon, 26 Nov 2018 14:13:50 +0000

>> BALAZS: I personally completely hate the empty type. I prefer explicit data.

OK.

At the moment, the flags seem to be between "deprecated nodes are 
present" or "deprecated nodes are not present", but I don't think that 
is the right choice.  Instead the binary choice should be between 
"deprecate nodes are present" and "behaviour is not defined".  Similarly 
for the obsolete nodes.

Thanks,
Rob

> .

---

From: Balázs Lengyel <[email-masked]>
Date: Mon, 26 Nov 2018 15:27:46 +0000

As we want to promote the default settings:
deprecated=implemented, obsolete=not-implemented,

maybe it should be:

deprecated: implemented/undefined

obsolete: not-implemented/undefined

Balazs

On 2018. 11. 26. 15:13, Robert Wilton
wrote:

At the
moment, the flags seem to be between "deprecated nodes are
present" or "deprecated nodes are not present", but I don't think
that is the right choice.  Instead the binary choice should be
between "deprecate nodes are present" and "behaviour is not
defined".  Similarly for the obsolete nodes.

Thanks,

Rob

---

From: Robert Wilton <[email-masked]>
Date: Mon, 26 Nov 2018 15:32:18 +0000

On 26/11/2018 15:27, Balázs Lengyel wrote:
>
> As we want to promote the default settings: deprecated=implemented, 
> obsolete=not-implemented,
> maybe it should be:
>
>   * deprecated: implemented/undefined
>   * obsolete: not-implemented/undefined
>
Yes.

Thanks,
Rob

> Balazs
>
> On 2018. 11. 26. 15:13, Robert Wilton wrote:
> Mobile: +36-70-330-7909              email:[email-masked]  
>

---

From: Joe Clarke <[email-masked]>
Date: Mon, 26 Nov 2018 10:33:28 -0500

>>   * obsolete: not-implemented/undefined

That is consistent with what we discussed in BKK.

Joe

---

From: Robert Wilton <[email-masked]>
Date: Tue, 27 Nov 2018 10:28:06 +0000

One other change we should consider for the YANG library section is 
currently it is augmenting the sub-module list with a semver.

If we get to the conclusion that the semver only applies at the module 
level, and if we don't have any file specific semver for each sub-module 
then I think that we should remove the sub-module list semver 
augmentation, and only augment the YANG version at the module list 
level.  Specifically having the duplicate value for each sub-module 
doesn't seem to give an extra useful information, and gives the 
implication that they could differ.

Thanks,
Rob

---

From: Balázs Lengyel <[email-masked]>
Date: Tue, 27 Nov 2018 10:29:32 +0000

Yes. Balazs

On 2018. 11. 27. 11:28, Robert Wilton wrote:
> level, and if we don't have any file specific semver for each 
> sub-module then I think that we should remove the sub-module list 
> semver augmentation, and only augment the YANG version at the module 
> list level.  Specifically having the duplicate value for each 
> sub-module doesn't seem to give an extra useful information, and gives 
> the implication that they could differ.
>
> Thanks,
> Rob
>