Subject: [yang-doctors] [IANA #1173669] questions about IANA-maintained YANG modules

From: "Amanda Baber via RT" <[email-masked]>
Date: Mon, 06 Jul 2020 18:41:43 +0000

Dear YANG Doctors,

I'm afraid we have more questions about references in revision comments.

We sometimes make registrations in the Address Family Numbers, SAFI Values, and ifType registries for individual requesters, non-IETF standards documents, and I-Ds that haven't been sent to IETF Last Call yet. When we add entries like this to a YANG module, do we need to include a reference in the revision comment?

These are some examples of entries in the "Reference" field for recent registrations:

Nischal Sheth
draft-kaliraj-idr-bgp-classful-transport-planes-00
IEEE 1906.1-2015

Another question: we initially missed the requirement to include references in revision statements. Can we add missing references to existing revision statements and then add a single blanket revision statement (with no reference) noting that we added the missing references?

If we introduce a typo into an IANA-maintained YANG module, can we make the correction without adding a revision statement and changing the date in the filename?

thanks,
Amanda

---

From: Mahesh Jethanandani <[email-masked]>
Date: Mon, 6 Jul 2020 19:01:34 -0700

Hi Amanda,

> On Jul 6, 2020, at 11:41 AM, Amanda Baber via RT <[email-masked]> wrote:
> 
> Dear YANG Doctors,
> 

I, as a common practice do include a reference in the revision statement. That reference is usually to most important document that describes the module in question.

> If we introduce a typo into an IANA-maintained YANG module, can we make the correction without adding a revision statement and changing the date in the filename?

In my mind, a module revision statement needs to be bumped if there is a significant change in the module. A typo or adding a missing reference does not rise to the level of a significant change in my mind.

Thanks.

> 
> thanks,
> Amanda
> 
> _______________________________________________
> yang-doctors mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/yang-doctors

Mahesh Jethanandani
[email-masked]

---

From: "Acee Lindem (acee)" <[email-masked]>
Date: Tue, 7 Jul 2020 10:21:53 +0000

As a co-author of RFC 8294, I would agree.
Thanks,
Acee

On 7/6/20, 10:01 PM, "yang-doctors on behalf of Mahesh Jethanandani" <[email-masked] on behalf of [email-masked]> wrote:

    Hi Amanda,

    Thanks.

    Mahesh Jethanandani
    [email-masked]

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Tue, 7 Jul 2020 12:05:28 +0000

Hi Amanda,

As a heads up, or possibly a reminder, there is work happening in NETMOD regarding versioning YANG modules.

Two of these documents are likely to have some potential impact on how IANA manages YANG Modules (in particular, using a statement to flag when non-backwards-compatible changes have occurred, and assigning semantic version numbers based on the changes - which will require that IANA is able to determine whether a change is backwards compatible or not (pyang can help with this)).

The two drafts in question are (updated versions will be posted shortly):
  https://tools.ietf.org/html/draft-verdt-netmod-yang-module-versioning-01
  https://tools.ietf.org/html/draft-ietf-netmod-yang-semver-00

I have flagged with the authors that we need to add instructions from IANA on how to manage YANG documents, and also an early review from IANA to check that they are happy with the instructions that we propose.  However, the documents are not quite ready for that yet - just a heads up.

With that background, and back to your questions on this thread, I've added comments online ...

> -----Original Message-----
> From: yang-doctors <[email-masked]> On Behalf Of Acee
> Lindem (acee)
> Sent: 07 July 2020 11:22
> To: Mahesh Jethanandani <[email-masked]>; iana-issues-
> [email-masked]
> Cc: [email-masked]
> Subject: Re: [yang-doctors] [IANA #1173669] questions about IANA-
> maintained YANG modules
> 
> On 7/6/20, 10:01 PM, "yang-doctors on behalf of Mahesh Jethanandani"
> <[email-masked] on behalf of [email-masked]>
> wrote:
> 
>     Hi Amanda,
> 
>     > We sometimes make registrations in the Address Family Numbers, SAFI
> Values, and ifType registries for individual requesters, non-IETF
> standards documents, and I-Ds that haven't been sent to IETF Last Call
> yet. When we add entries like this to a YANG module, do we need to include
> a reference in the revision comment?
[RW] 
Yes, I think that adding the reference to where it has been defined is always helpful.

> 
>     I, as a common practice do include a reference in the revision
> statement. That reference is usually to most important document that
> describes the module in question.
> 
>     >
>     > Another question: we initially missed the requirement to include
> references in revision statements. Can we add missing references to
> existing revision statements and then add a single blanket revision
> statement (with no reference) noting that we added the missing references?
[RW] 
Yes, this would be fine.

>     >
>     > If we introduce a typo into an IANA-maintained YANG module, can we
> make the correction without adding a revision statement and changing the
> date in the filename?
[RW] 
No, it probably should be marked as a new revision, please see below.

> 
>     In my mind, a module revision statement needs to be bumped if there is
> a significant change in the module. A typo or adding a missing reference
> does not rise to the level of a significant change in my mind.
[RW] 

The current thinking of the versioning authors (no IETF consensus yet) is that "any change" to a YANG document must result in a new revision. This includes fixing a typo, adding or changing any YANG statements to the module, and probably even covers insignificant whitespace changes caused by reformatting.

Regards,
Rob

---

From: "Sabrina Tanamal via RT" <[email-masked]>
Date: Tue, 14 Jul 2020 22:55:10 +0000

Hi all, 

Thank you all for your feedback. It appears there are different opinions in the comments we've received. Does this need to be discussed further so we can come to a consensus? 

Best regards, 

Sabrina Tanamal
Senior IANA Services Specialist

On Tue Jul 07 12:06:11 2020, [email-masked] wrote:
> Hi Amanda,
> 
> As a heads up, or possibly a reminder, there is work happening in
> NETMOD regarding versioning YANG modules.
> 
> Two of these documents are likely to have some potential impact on how
> IANA manages YANG Modules (in particular, using a statement to flag
> when non-backwards-compatible changes have occurred, and assigning
> semantic version numbers based on the changes - which will require
> that IANA is able to determine whether a change is backwards
> compatible or not (pyang can help with this)).
> 
> I have flagged with the authors that we need to add instructions from
> IANA on how to manage YANG documents, and also an early review from
> IANA to check that they are happy with the instructions that we
> propose.  However, the documents are not quite ready for that yet -
> just a heads up.
> 
> The current thinking of the versioning authors (no IETF consensus yet)
> is that "any change" to a YANG document must result in a new revision.
> This includes fixing a typo, adding or changing any YANG statements to
> the module, and probably even covers insignificant whitespace changes
> caused by reformatting.
> 
> Regards,
> Rob
> 
> 
> >
> > Thanks.
> >
> >     >
> >     > thanks,
> >     > Amanda
> >     >

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Wed, 15 Jul 2020 07:34:10 +0200

The simplest approach seems to be to add all missing references etc.
and to issue the result with a new revision statement describing that
references etc. got added.

/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/>