Subject: Re: [yang-doctors] guideline for enum and value?

From: Benoit Claise <[email-masked]>
Date: Wed, 14 Feb 2018 16:25:48 +0100

Dear all,

Trying to see if there is a common guideline among YANG doctors (to be 
added in RFC6087bis)

What about a mix of:

   YANG automatically assigns numeric values to enums if no values are
   specified. This automatic assignment requires that (a) the order of
   enums never changes and (b) additional enums are only appended but
   never prepended or inserted.

And:

  Do not use explicit 'value' statements, except if:
     o the enum corresponds to some standard integer value, or
     o you update the set of enums by inserting new enums in the middle 
of the list

Regards, B.

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 14 Feb 2018 16:47:40 +0100

On Wed, Feb 14, 2018 at 04:25:48PM +0100, Benoit Claise wrote:
> Dear all,
> 
> Trying to see if there is a common guideline among YANG doctors (to be added
> in RFC6087bis)
> 
> What about a mix of:
> 

OK
 
>     o you update the set of enums by inserting new enums in the middle of
> the list

I am not sure why we would recommend this.

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <https://www.jacobs-university.de/>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 14 Feb 2018 16:59:51 +0100

> I am not sure why we would recommend this.

More specifically, I do not see why

  type enumeration { enum foo { value 0; }; enum bar { value 1; }; }

is to be avoided in favor of

  type enumeration { enum foo; enum bar; }

given that they mean the same and the first one is explicit and robust
to changes while the second one must be handled with care (only append
enums, never reorder enums). Yes, clueful YANG authors can handle the
later fine as they will understand that if order changes are needed,
you have to move to explicit value assignments. My fear is that not
all YANG authors will be aware of this (but then many of those authors
likely also do not read guidelines).

/js

---

From: "Einar Nilsen-Nygaard (einarnn)" <[email-masked]>
Date: Wed, 14 Feb 2018 16:19:58 +0000

For me it's about who the values of the enums are for, and the impact on model evolution in different places. The enum values are explicitly intended as for model implementers to use, and have no real meaning to model consumers as the canonical representation is the string identifier. However, once a value is assigned via a "value", that value may never change. I have seen developers naively assign explicit values from other sources (e.g. system header files on the OS) and then inadvertently see problems when they implement the model on top of a new OS, where the value matching the symbol is not the same, and so the developers just (illegally) changed the value in the value clause. This still has zero impact on the end consumer of the model, as they deal with the string, but is a backwards compatibility violation that need not have happened.

In general, I think embedding values that are primarily targeted to implementers of a model in what is also the external format is just not all that helpful.

Not a huge deal, but reduces coupling, reduces opportunity for inadvertent backwards-compatibility breakage, and encourages better implementation code/model hygiene as all parties will be encouraged to utilize symbols rather than flawed values. I would like to see both consumers and implementers of models get to the point where:

and

type enumeration { enum bar; enum foo; }

...are ultimately treated the same and such that reordering of symbols doesn't break things. I've seen enough broken code based on order-dependent integer value assignments combined with people using the values instead of symbols to last several lifetimes, and anything we can do to remove opportunities for mistakes seems like a good thing.

Cheers,

Einar

On Feb 14, 2018, at 3:59 PM, Juergen Schoenwaelder <[email-masked]<mailto:[email-masked]>> wrote:

And:

/js

---

From: Jan Lindblad <[email-masked]>
Date: Wed, 14 Feb 2018 17:28:09 +0100

Einar,

FWIW, the ConfD NETCONF server implementation has a *programming API* which is stable against enum order changes in the YANG as described below. I.e. that can still be an implementation decision. I agree, though, that depending on implicit order is risky, and that's exactly why we avoid this in the APIs.

/jan

> On 14 Feb 2018, at 17:19, Einar Nilsen-Nygaard (einarnn) <[email-masked]> wrote:
> 
>> On Feb 14, 2018, at 3:59 PM, Juergen Schoenwaelder <[email-masked] <mailto:[email-masked]>> wrote:
>> 
>> Fax:   +49 421 200 3103         <https://www.jacobs-university.de/ <https://www.jacobs-university.de/>>
> 
> _______________________________________________
> yang-doctors mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/yang-doctors

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 14 Feb 2018 17:52:13 +0100

Once again, see the CBOR encoding work where they do make use of the
enum value on the wire (draft-ietf-core-yang-cbor-05 section 5.6).

/js

---

From: "Acee Lindem (acee)" <[email-masked]>
Date: Wed, 14 Feb 2018 17:14:31 +0000

I agree. 

On 2/14/18, 11:00 AM, "yang-doctors on behalf of Juergen Schoenwaelder" <[email-masked] on behalf of [email-masked]> wrote:

    

    

    /js

---

From: Andy Bierman <[email-masked]>
Date: Wed, 14 Feb 2018 09:35:31 -0800

> enum value on the wire (draft-ietf-core-yang-cbor-05 section 5.6).
The CBOR encoding is extremely fragile and does not work if the enum is in
a union type.

I think this YANG guideline is from the 1st RFC.

The enum and bit values in YANG are rather misleading since they do not
appear
in any protocol operations.

They add no value at all if the type has no use for them.
SMIv2 is full of busy work the authors must complete.
Looks like you want YANG to be the same way.

> /js

Andy

> > For me it's about who the values of the enums are for, and the impact on
> model evolution in different places. The enum values are explicitly
> intended as for model implementers to use, and have no real meaning to
> model consumers as the canonical representation is the string identifier.
> However, once a value is assigned via a "value", that value may never
> change. I have seen developers naively assign explicit values from other
> sources (e.g. system header files on the OS) and then inadvertently see
> problems when they implement the model on top of a new OS, where the value
> matching the symbol is not the same, and so the developers just (illegally)
> changed the value in the value clause. This still has zero impact on the
> end consumer of the model, as they deal with the string, but is a backwards
> compatibility violation that need not have happened.
> >
> > In general, I think embedding values that are primarily targeted to
> implementers of a model in what is also the external format is just not all
> that helpful.
> >
> > Not a huge deal, but reduces coupling, reduces opportunity for
> inadvertent backwards-compatibility breakage, and encourages better
> implementation code/model hygiene as all parties will be encouraged to
> utilize symbols rather than flawed values. I would like to see both
> consumers and implementers of models get to the point where:
> >
> > ...are ultimately treated the same and such that reordering of symbols
> doesn't break things. I've seen enough broken code based on order-dependent
> integer value assignments combined with people using the values instead of
> symbols to last several lifetimes, and anything we can do to remove
> opportunities for mistakes seems like a good thing.
> >
> > Cheers,
> >
> > Einar
> >
> > On Feb 14, 2018, at 3:59 PM, Juergen Schoenwaelder <
> [email-masked]<mailto:j.schoenwaelder@jacobs-
> university.de>> wrote:
> >

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 14 Feb 2018 19:02:46 +0100

> Looks like you want YANG to be the same way.

You got it.

/js

---

From: "Einar Nilsen-Nygaard (einarnn)" <[email-masked]>
Date: Wed, 14 Feb 2018 18:41:52 +0000

Juergen,

The CBOR text does not invalidate the rationale I have discussed below. I recognize that the CBOR approach would break between model revisions if model authors arbitrarily reordered enums, but since that is already counter to RFC7950 backwards-compatibility guidelines, that is a non-issue.

So, even with the CBOR intent to use numeric wireline encoding, avoiding the explicit use of the value statement still seems like an overall benefit to the majority of developers.

Cheers,

Einar

> On Feb 14, 2018, at 4:52 PM, Juergen Schoenwaelder <[email-masked]> wrote:
>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 14 Feb 2018 19:52:34 +0100

> So, even with the CBOR intent to use numeric wireline encoding, avoiding the explicit use of the value statement still seems like an overall benefit to the majority of developers.

Developers can shoot themself into the food in either way. So how are
we going to declare that one way of shooting yourself into the food it
better than the other?

Here is my reasoning: If developers go and change explicit enum
values, I believe they more likely realize that they break a contract
by doing so. If they just change the order of enum definitions, they
may not realize that they also changed the value associated with an
enum. This is my reasoning.

And yes, RFC 7950 section 11 first bullet clear says that regardless
how you shoot yourself into the food, it will hurt. So we can be
entirely silent about this because RFC 7950 section 11 really nails
it.

/js

---

From: "Einar Nilsen-Nygaard (einarnn)" <[email-masked]>
Date: Wed, 14 Feb 2018 19:46:08 +0000

On Feb 14, 2018, at 6:52 PM, Juergen Schoenwaelder <[email-masked]<mailto:[email-masked]>> wrote:

Practical experience is one thing. I have had to deal very directly with this issue in embedded OS development in my day job, and I can say that had developers not used the value statement, things would have been easier. And so when it comes to the teams I work with, we have put this recommendation in place already, and that advice will not change irrespective of what this thread may, or may not, recommend.

And I'm fine with that! :-)

You're making assumptions in this about the organizational structure and responsibilities of teams and the toolchains used that don't hold true everywhere when you say this, which is fine; it's also what I'm doing when I say that your reasoning above wouldn't have helped my scenario :-)

Fine, that works.

Cheers,

Einar

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 14 Feb 2018 21:00:28 +0100

Sorry, quoting messed up, not my fault...

> And I'm fine with that! :-)

We had the case in the IETF where people wanted to create enums but
could not guanrantee that the order does not change. Practical
experience against practical experience. As I said, you can shoot
yourself in the foot either way. I believe one way is more subtle
since it comes as a side effect and not as a result of a direct
edit. But that is not your experience yet, so here we are.
 
> You're making assumptions in this about the organizational structure and responsibilities of teams and the toolchains used that don't hold true everywhere when you say this, which is fine; it's als…

All fine - as I said there are multiple ways to screw up and there is
not clear reason why one is worse then the other (althought I keep
claiming that changing values as a side effect of changing order is
more subtle than changing values explicitely).

> entirely silent about this because RFC 7950 section 11 really nails

Good. So lets just point to RFC 7950 section 11.

/js