Hi all,
We need to get to a better process for IETF YANG models. The current approach
is not working. Hence my proposal:
Having an RFC that describes the purpose, high level overview, key
structure/design decisions for the YANG module(s) makes sense to me. If any of
those aspects change then the RFC should be bis'ed or have an updates RFC that
specifies the extra functionality, but probably having just one doc is best for
the reader.
I think that the RFC could/should also contain:
*
Informative tree snippets to illustrate the structure.
*
Informative examples of how to use the YANG module.
*
References to where to find:
*
The latest stable (with IETF consensus) version of the YANG module, tree
diagram and verifiable instance data examples. These should probably be
available on GitHub, but also somewhere that has long term archival quality,
i.e., IANA or the RFC Editor.
*
The latest development version of the YANG module, tree diagram and verifiable
instance data examples. These would just be available on Github.
I think that RFC should not contain (because they can change more frequently):
*
The YANG module
*
Normative tree output
*
Normative examples
*
Any nitty/gritty details or explanations of specific fields - they should be in
protocol specifications or in the YANG module itself.
Things like errata or bug fixes should just be applied to the latest YANG
modules/examples. After these have been reviewed/approved by the AD (and
perhaps the RPC centre) then the stable version of the YANG modules can be
updated (with new revision dates/versions - but note, they won't always be
patches, that could be minor, or even major version changes for a NBC bugfix).
Minor additions to the YANG module can be made on the development branch. On a
periodic basis (nominally once every 2 years, but more frequently if there is a
particular demand) then we can run the the IETF process to check for consensus
on the diffs between latest and the stable version(s) to promote the latest
development versions to become the new stable versions.
Running the IETF process could be achieved in three ways:
1.
Bis the original RFC, update the references to the latest code and follow the
regular IETF process exactly. I don't like this so much because it increases
the workload for everyone and risks introducing more changes than desirable
(since all text in the RFC/YANG modules would be open for review/update).
2.
Bis the original RFC, updating the references to the latest code. Follow the
IETF process but limit the reviews/comments to only changes in the diffs or
what has changed (with permissions for the ADs to override). The diffs could
be included in the appendix of the bis-draft to be stripped out by the RPC when
the draft reaches that stage.
3.
Create a draft (as Joe suggests auto-created by tooling) that just represents
the diff to the YANG modules and examples and run that through the process.
This could potentially cover multiple models at the same time. I'm not sure
that it makes sense to publish this as an RFC, or whether that would end up
just being noise, and at the end of the process, it just gets binned.
I will likely propose a similar approach for YANG packages when we get to those.
Kind regards,
Rob
From: tom petch <[email protected]>
Date: Thursday, 13 November 2025 at 12:26
To: Andy Bierman <[email protected]>, Joe Clarke (jclarke)
<[email protected]>
Cc: opsawg <[email protected]>
Subject: [OPSAWG]Re: Thoughts on VELOCE
From: Andy Bierman <[email protected]>
Sent: 12 November 2025 20:58
On Wed, Nov 12, 2025 at 10:13 AM Joe Clarke (jclarke)
<[email protected]<mailto:[email protected]>> wrote:
NO HATS.
For those that tuned in to the IETF 124 opsawg meeting, you know I made the
bold statement during Mahesh’s VELOCE presentation, why do we need an I-D for a
YANG module? My point was that the I-D — and by extension, the IETF process —
slows down the development of YANG modules, which has led to other efforts like
OpenConfig being more prevalent in the industry. Additionally, I find in many
cases the I-D attracts text that would better be put into the YANG module
itself (e.g., extra implementation details in leaf descriptions). This means
someone implementing or using the YANG module can’t simply rely on it as the
sole documentation for implementation.
Jeff Haas and Rob Wilton addressed my “devil’s advocate” boldness by explaining
that an I-D is what the IETF works on and that some text is best left to the
I-D. Valid points. It was also mentioned that maybe only the initial YANG
module needs a draft, whereas minor updates could just happen in GitHub and
vendors could state that they implement a given YANG Semver version of those
YANG modules.
Still, with all the boiler plating and tools we have for YANG (considering
8407bis, pyang for trees, yanglint for instance data validation, yangson and
the nascent work on example coverage) I don’t see why a module — even a net-new
module — couldn’t be initially developed in GitHub with an I-D being
auto-generated from artifacts in that repo. That is, if the expectation is one
would create a YANG module and various example instance data, the I-D could be
generated with examples, trees, security considerations, IANA considerations,
etc. It won't be perfect, but it would give the authors a strong starting
point. Dare I say, fold generative AI into this, and examples and template
sections can be roughed out automatically.
I admit this doesn't work for all YANG modules. Certainly, the YANG modules in
the YANG versioning work need more surrounding prose. This approach would be
more suited to device-centric YANG data models. I cooked up an experiment in
my own GH<https://github.com/xorrkaz/ietf-syslog-experiment> using the recently
standardized ietf-syslog module. It was quick. Took about 20 minutes or so,
and it did okay.
But would more rapid I-D generation (or no I-D at all) really speed up the YANG
process? Not if the full IETF process still must happen for vendors to
implement modules. Not if vendors don’t like the piecemeal nature of IETF YANG
modules. However, if (ideally, when) YANG Packages is standardized, publishing
packages in GitHub along with rapid prose work around any I-Ds that may be
required might be the best answer to holistically improving the process.
As a YANG Doctor, I like having the I-D text to help me understand the module I
have to review.
It would be great if tooling could help generate most of this text somehow.
The published RFC is still very important for standards conformance.
<tp>
I think that the RFC format is also very important. To an expert, such as an
implementer, the YANG module is likely all that is needed. For most people,
more is needed by way of context. To a non-expert on the subject of the YANG
module, like me in most cases, then the format of Abstract, Introduction and so
on enables me to decide how far into the detail I want to go, how much of my
time it is worth spending on it; I think that this is a generic truth. Experts
talk to other experts in a different way, not intending to exclude others but
often doing so. The RFC format allows everyone to engage as much as is
appropriate for them.
Tom Petch
Removing the I-Ds from the process might make it hard to produce an RFC, unless
the tooling is good enough.
I understand that too much text outside the YANG module creates duplication and
ambiguity.
Cut-and-paste to avoid ambiguity is not a good solution.
It would be really great if Verified Errata were applied to YANG modules (and
all RFCs) instead
of requiring readers to manually figure out the edits. Now that we have YANG
Semver, it should
be easy to publish errata as patch releases. The RFC is published as X.Y.0 and
any later release X.Y.*
is considered to be the official RFC module. The full process should be
eliminated for patch updates.
Maybe minor release updates could also be streamlined, but I am just suggesting
this for a patch update.
Joe
Andy
Cisco Confidential
_______________________________________________
OPSAWG mailing list -- [email protected]<mailto:[email protected]>
To unsubscribe send an email to
[email protected]<mailto:[email protected]>
_______________________________________________
OPSAWG mailing list -- [email protected]
To unsubscribe send an email to [email protected]
_______________________________________________
OPSAWG mailing list -- [email protected]
To unsubscribe send an email to [email protected]
