I sort of don’t mind too much what we do. In general, it would be sensible if the tooling is able to just extract that useful/valid YANG modules and exclude examples.
But I can also see the desire to automatically see that the examples are valid. Note that there are cases where the examples are incomplete in some way to make them shorter and more meaningful. For the markdown scripting that I use to build the YANG Push lite draft: * It uses rfcstrip and throws away non .yang files and anything with example in the name. * It uses yanglint to validate the instance data examples as separate files before adding them to draft. This also has the advantage that I can also ensure that I have fetched all the dependent YANG module versions that I need to validate the example. But I also agree with Andy that we shouldn’t automatically be extracting anything that won’t easily validate. Kind regards, Rob From: Andy Bierman <[email protected]> Date: Tuesday, 30 September 2025 at 03:24 To: Mahesh Jethanandani <[email protected]> Cc: tom petch <[email protected]>, Rob Wilton (rwilton) <[email protected]>, NetMod WG <[email protected]> Subject: Re: Should example modules be allowed to use code tags [Re: [netmod] AD review of draft-ietf-netmod-intf-ext-yang-16] On Mon, Sep 29, 2025 at 6:01 PM Mahesh Jethanandani <[email protected]<mailto:[email protected]>> wrote: [Changing the subject line as the discussion is tangential to the work at hand] Hi Andy/Tom, Here is how I am trying to rationalize this: · Should (complete, and not code snippets) example modules (or instance data examples) be validated? Per rfc8407bis, Section 3.2.1, it is pretty clear that they should be validated. · Are those examples normative? The answer is no, and that is why the examples should exist in the non-normative section of the draft. · Separate from that, the question is how the examples can be validated? The tools can validate them only if they are standalone files. To create those standalone files, they have to be extracted from the draft. Would you agree that how we extract them is less important than being able to do so? I was referring to snippets, not full modules, and not instance examples. I agree that complete modules should be validated, especially example modules meant to demonstrate how to augment the base module in the RFC. Currently, rfcstrip extracts all CODE BEGINS/ENDS blocks, which is correct. IMO the YANG guideline is wrong, and it is OK to put this wrapper around complete non-normative modules. We can discuss whether we need a different tag to extract (complete) examples, but given the current toolset, I do not believe we have a conflict in how the examples are extracted and named. Cheers. Andy On Sep 24, 2025, at 9:36 AM, Andy Bierman <[email protected]<mailto:[email protected]>> wrote: On Wed, Sep 24, 2025 at 4:26 AM tom petch <[email protected]<mailto:[email protected]>> wrote: From: Mahesh Jethanandani <[email protected]<mailto:[email protected]>> Sent: 23 September 2025 21:47 Hi Tom, My take is that code markers only say where the code begins and where it ends. It does not distinguish between it being YANG, MIB, an example or any other piece of code. The code markers can specify which file the said code should extract into. We do not need separate code markers for different pieces of code. <tp> Colour me confused. If we do not need separate code markers for different 'types' of code (which I agree with), then that tells me that the CODE START and CODE END should not appear in this I-D but should be replaced by CODE BEGINS and CODE ENDS. Correct. https://www.ietf.org/archive/id/draft-ietf-netmod-rfc8407bis-28.html#name-code-components Note that the MUST NOT rule in 3.2.1 is not being followed, and example modules are commonly documented as code components. There was discussion about EXAMPLE BEGINS/ENDS, but a new macro like that was not added. There was discussion about the importance of IETF Trust IPR issues associated with code components. That is why the guidelines draft distinguishes between normative and non-normative YANG modules. Since examples are quite common in all I-Ds, this seems like an important precedent being set here. As a consumer of RFCs, I do not really want dozens of extracted files for ad-hoc example snippets. These snippets are not code components, and it would be better to handle example validation another way. Mahesh Jethanandani [email protected]<mailto:[email protected]>
_______________________________________________ netmod mailing list -- [email protected] To unsubscribe send an email to [email protected]
