[netmod] Re: draft-ietf-iana-yang-guidance-01

[Qin Wu <[e-mail]>]

Joe:
thanks for reminding me who will be audience for this work, i originally thought yang data model authors are also readers, your clarification makes  sense to me, thanks.

发件人：Joe Clarke (jclarke) <[e-mail]<mailto:[e-mail]>>
收件人：Qin Wu <[e-mail]<mailto:[e-mail]>>;Rob Wilton (rwilton) <rwilton=[e-mail]<mailto:rwilton=[e-mail]>>;Sandy Ginoza <[e-mail]<mailto:[e-mail]>>;[e-mail] <[e-mail]<mailto:[e-mail]>>;[e-mail] <[e-mail]<mailto:[e-mail]>>;Mahesh Jethanandani <[e-mail]<mailto:[e-mail]>>;Mohamed Boucadair <[e-mail]<mailto:[e-mail]>>;NETMOD Working Group <[e-mail]<mailto:[e-mail]>>
抄 送：NETMOD WG <[e-mail]<mailto:[e-mail]>>
时 间：2026-07-23 09:04:28
主 题：Re: draft-ietf-iana-yang-guidance-01

In this case, I think we want to be very prescriptive as to what IANA is to do as YANG is not their full-time job.  If tooling does change, then I think we would want to do a bis to update that process and again be prescriptive with what exact steps IANA is to perform.

Joe

From: Qin Wu <[e-mail]>
Date: Thursday, July 23, 2026 at 00:42
To: Rob Wilton (rwilton) <rwilton=[e-mail]>; Sandy Ginoza <[e-mail]>; [e-mail] <[e-mail]>; [e-mail] <[e-mail]>; Mahesh Jethanandani <[e-mail]>; Mohamed Boucadair <[e-mail]>; Joe Clarke (jclarke) <[e-mail]>; NETMOD Working Group <[e-mail]>
Cc: NETMOD WG <[e-mail]>
Subject: RE: draft-ietf-iana-yang-guidance-01

Hi, Rob:
Thanks for taking care of my comments, I believe some of clarification text is needed. Regarding pyang tooling, I know it has already been used widely, however how do we when pyang has been evolved or replace by other byang, cyang tools, my only suggestion is to make “6.4.4. <https://datatracker.ietf.org/doc/html/draft-ietf-netmod-iana-yang-guidance-02#section-6.4.4> Step 4: Use Pyang Tooling to Check/Recommend Next Version<https://datatracker.ietf.org/doc/html/draft-ietf-netmod-iana-yang-guidance-02#name-step-4-use-pyang-tooling-to>” generic, e.g., Use YANG Validation tooling to check/Recommended Next Version. It is not necessary to make bisdocument for such minor change, I think VELOCE might face similar issue, I don’t know what are best way to address this.
Thanks!

-Qin
发件人: Rob Wilton (rwilton) <rwilton=[e-mail]>
发送时间: 2026年7月22日 13:19
收件人: Qin Wu <[e-mail]>; Sandy Ginoza <[e-mail]>; [e-mail]; [e-mail]; Mahesh Jethanandani <[e-mail]>; Mohamed Boucadair <[e-mail]>; Joe Clarke (jclarke) <[e-mail]>; NETMOD Working Group <[e-mail]>
抄送: NETMOD WG <[e-mail]>
主题: Re: draft-ietf-iana-yang-guidance-01

Hi Qin,

Thank you for this review.  I fear that I have missed addressing your comments in the -03 version, but I will check them and apply them to the next version before we go for WG LC.

Please see inline [RW] ...

From: Qin Wu <bill.wu=[e-mail]<mailto:bill.wu=[e-mail]>>
Date: Wednesday, 15 April 2026 at 06:26
To: Rob Wilton (rwilton) <[e-mail]<mailto:[e-mail]>>; Sandy Ginoza <[e-mail]<mailto:[e-mail]>>; [e-mail]<mailto:[e-mail]> <[e-mail]<mailto:[e-mail]>>; [e-mail]<mailto:[e-mail]> <[e-mail]<mailto:[e-mail]>>; Mahesh Jethanandani <[e-mail]<mailto:[e-mail]>>; Mohamed Boucadair <[e-mail]<mailto:[e-mail]>>; Joe Clarke (jclarke) <[e-mail]<mailto:[e-mail]>>; NETMOD Working Group <[e-mail]<mailto:[e-mail]>>
Cc: NETMOD WG <[e-mail]<mailto:[e-mail]>>
Subject: RE: draft-ietf-iana-yang-guidance-01
Hi, Rob:
Thanks for the update to draft-ietf-iana-yang-guidance, I take some time to review the latest version and have the following comments and input, hope it helps:

1.       Section 2 said:
“This document provides informational guidance to both the RFC Editor and IANA for managing YANG modules in two distinct scenarios:”
[QW]: This document provide guidance for both RFC Editor and IANA?
I am wondering whether YANG module authors need to pay attention to this informational guidance?

[RW] This guidance is only aimed at the RFC Editor and IANA.  I think that we have existing YANG Author guidelines and the versioning docs that apply to authors.

Or the principle is
If YANG module author don’t follow this guidance or don’t need to worry about this guidance before IESG review, RFC Editor and IANA has right to block publication of this documents after IESG review until Module version gets corrected?

[RW] YANG Module authors in the IETF would be expected to get this right (with help from the YANG Doctor's reviews).  Some of the recommendations in this document are to help ensure that the version rules/formatting have been applied correctly at RFC publication time.

Section 4.1 said:
“_COMPAT is used for branched development trees and is not applicable to normative modules published by the IETF or IANA-maintained modules.
”
[QW]:Look at the definition of _COMPACT:
”
_COMPAT is used for branched development trees and is not applicable to normative modules published by the IETF or IANA-maintained modules.
”
It is not clear to me how to understand normative module? Do we emphasize _COMPACT is optional parameter instead of mandatory parameter?
Or Is _COMPAT designed for pre-release version?

[RW] By normative, I think that we mean non-example YANG modules, but I think suggestion may have come in from Med.  I'll see if I can clarify that slightly.  The _COMPAT is mostly expected to be used for vendor publishing their own YANG modules rather than those produced by an SDO.

Section 4.1 also said:
“
….
e.g., as per the second example below.

”
[QW]:Where the second example below is documented? In which section?
Section 4.1 said:
“
Pre-release versions (versions with MAJOR = 0, e.g., "0.2.0", or with a pre-release suffix, e.g., "1.3.0-04")

”
[QW]: I understand -04 is internet-draft-number and is used to compatible with semver and can be seen as version  label, however such pre-release suffix used in many place not consistent, e.g., Section 5.2,1 said:
“any normative YANG modules it contains typically have pre-release version numbers (e.g., 0.4.0, 1.1.0-03, or 2.0.0-07)”
Section 4.4 said:
“
Modules in Internet-Drafts MUST use pre-release versions (e.g., 0.1.0 or 2.0.0-draft-name) to indicate that the content may still change.

”
Here draft-name is referred to full draft name or draft number, I think such inconsistency needs to be addressed.

[RW] I agree and I will check (against the Semver draft) and ensure that this is consistent with that draft and internally consistent in this draft.

Section 5.2.2 said:
“
consult with the authors to determine the correct version number and whether the rev:non-backwards-compatible extension is required.

”
[QW]: Who should be consulted to determine the correct version number and whether the rev:non-backwards-compatible extension is required.
Section 5.2.2 said at the RFC Editor Processing stage, the draft authors should be consulted.
Section 7 said, YANG Doctor should be consulted
At the RFC Editor Processing stage combine together with other circumstances such as:
1.      Classification Uncertainty
2.      Tool Disagreement
3.      Description Changes
4.      Unusual Situations
5.      Registry Restructuring

[RW] I will check the text.  My expectation is that the RFC Editor should be able to check (using tooling).  If it is unusual then they should check with the authors.  The YANG Doctors (via the YANG Doctor Secretaries) are available to help give guidance if a more complicated situation arises.

Section 6.4.4 said:
“
6.4.4. <https://datatracker.ietf.org/doc/html/draft-ietf-netmod-iana-yang-guidance-02#section-6.4.4> Step 4: Use Pyang Tooling to Check/Recommend Next Version<https://datatracker.ietf.org/doc/html/draft-ietf-netmod-iana-yang-guidance-02#name-step-4-use-pyang-tooling-to>
”
[QW]: Do we need to separate guidance from specific tooling recommendation? Usually YANG Guidance doesn’t tie closely with specific YANG tools.
I search pyang, it has occurred for 27 times.

[RW] The idea here is that the documentation ties closely to the tools that are actually being used, because that gives the most useful concrete guidance.  If the use of that tooling changes over time, or different tooling is introduced then a bis version of this document could be generated.  I don't see any need for a separate draft on tooling unless IANA or the RFC Editor believes that is needed.

-Qin

[RW] Thanks again for the review and sorry for not replying sooner.

Kind regards,
Rob


发件人: Rob Wilton (rwilton) [mailto:rwilton=[e-mail]]
发送时间: 2026年4月14日 23:06
收件人: Sandy Ginoza <[e-mail]<mailto:[e-mail]>>; [e-mail]<mailto:[e-mail]>; [e-mail]<mailto:[e-mail]>; Mahesh Jethanandani <[e-mail]<mailto:[e-mail]>>; Mohamed Boucadair <[e-mail]<mailto:[e-mail]>>; Joe Clarke (jclarke) <[e-mail]<mailto:[e-mail]>>; NETMOD Working Group <[e-mail]<mailto:[e-mail]>>
抄送: NETMOD WG <[e-mail]<mailto:[e-mail]>>
主题: [netmod] Re: draft-ietf-iana-yang-guidance-01

Hi Amanda, Sabrina, Sandy, OPS ADs, NETMOD WG chairs, & Joe,

I've now just published draft-ietf-iana-yang-guidance-02, https://www.ietf.org/archive/id/draft-ietf-netmod-iana-yang-guidance-02.html

This incorporates the changes from the NETMOD discussion at IETF 125, and merges in review comments from Reshad, Joe, & Med.  Thanks Med!

There are no open issues against this document, and as such I am thinking about whether we should try and take this to WG LC already to flush out any further reviews!  Ideally, it would be nice if this draft could catch up with the other three post WG LC YANG versioning drafts (some of which will have an informative reference to this document) and hence get published at the same time - but we don't want to rush it if it is not complete/ready.

Note, there is still an open discussion point in https://datatracker.ietf.org/doc/draft-ietf-netmod-yang-module-filename/, that could change which character is used to identify a YANG file using a YANG Semver, which would require this doc to be updated with a small editorial change.

Hence, in our meeting today, we would like to request that IANA and the RFC Editor both review the document for readability/guidance and also check the workflow steps proposed in this document and workable and make sense.  Perhaps going through a sample workflow of trying a few imaginary registry changes and checking if you hit any issues with the workflow or need further clarification.

When using pyang to do the version comparison, then you will currently need to use the version in Joe's GitHub repository here (on the master branch): https://github.com/xorrkaz/pyang

Joe (or I, or one of the tools team) can probably help you get this setup if you need guidance.  But the basic steps are to pull a local copy of this github repository and then run "env.sh" from within the directory that git/GitHub copies the repository into.  Then your pyang invocations would pick up the new checks.

Alternatively, we could arrange a call and give a demo of how the tool would work if you think that would be helpful.  Please let me know if you would like me to try and set this up.

Finally, Mahesh, Med, is there anything that needs done from your side?  E.g., do you need to check with the IESG at all on what is proposed here, or can I assume that is either all in-hand, or will be dealt with during AD review or IESG review?

Kind regards,
Rob



From: Rob Wilton (rwilton) <rwilton=[e-mail]<mailto:rwilton=[e-mail]>>
Date: Tuesday, 17 March 2026 at 21:26
To: Sandy Ginoza <[e-mail]<mailto:[e-mail]>>, [e-mail]<mailto:[e-mail]> <[e-mail]<mailto:[e-mail]>>, [e-mail]<mailto:[e-mail]> <[e-mail]<mailto:[e-mail]>>, Mahesh Jethanandani <[e-mail]<mailto:[e-mail]>>, NETMOD WG <[e-mail]<mailto:[e-mail]>>, NETMOD Working Group <[e-mail]<mailto:[e-mail]>>
Subject: [netmod] draft-ietf-iana-yang-guidance-01
Hi all,

I've just published the -01 version of this draft that has quite a lot of updates and fixes and should hopefully incorporate the comments that I have received.   There is already a later version on GitHub (https://github.com/rgwilton/iana-yang-guidance?tab=readme-ov-file) that contains a couple more tweaks from Reshad and some spelling corrections.

As a reminder this is an informational draft, for which the abstract is:


This document provides guidance to the RFC Editor and IANA on managing YANG modules in RFCs and IANA registries, ensuring consistent application of YANG Semantic Versioning rules.


I'll be presenting this draft in the NETMOD session on Wednesday morning.

I think that there are 4 open issues that need to be addressed:

1.      Do we need guidance to IANA in this document to list modules both by revision date and version? I.e., following the filename convention.

2.      This document is informational, is it appropriate to use RFC 2119 language?

3.      For the RFC Editor and ADs, do we want to allow the RFC Editor to apply errata to IETF YANG modules?

4.      For Section 5<https://rgwilton.github.io/iana-yang-guidance/draft-ietf-netmod-iana-yang-guidance.html#sec-background>, should we give examples of the rules, or just reference the module versioning draft [Reshad]?

Depending on the feedback received it may be that we can get these addressed quickly, and then I'm wondering whether we will want [another] round of reviews, of whether it would make sense to go directly to WG LC?  On the one hand this document hasn't had that much in the way of reviews (it is quite new), but on the other hand it is only informational guidance and we are wanting to move it through the process quickly.

Kind regards,
Rob