From: Mahesh Jethanandani <[email protected]> Sent: 30 September 2025 02:00
[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? 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. <tp> An excellent suggestion for 8407bis to expand on. Ah, it is too far down the track for that, except that looking at 8407bis, I think that it is inconsistent. It says " Example modules are not code components. The <CODE BEGINS> convention MUST NOT be used for example modules. However, example modules MUST be validated (Section 3.10)." but how do you validate them when you do not have CODE BEGINS to automate the extraction? We need SAMPLE BEGINS and an update to the tool chain for validation! Without that, I think we are in a confusing state. The addition of that third sentence to the paragraph I quote has consequences that seem not to have been thought through. I would strike that third sentence, even at this late stage, and produce a separate I-D on the issue. The other unresolved issue is migration. For years to come, we are going to have modules that do not conform with 8407bis but there is no way of knowing which they are. We need something in a module, going forward, to say that it is intended to conform to 8407bis and is an error if it does not, just as when we updated YANG, we changed the version to 1.1 . Tom Petch Cheers. On Sep 24, 2025, at 9:36 AM, Andy Bierman <[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] _______________________________________________ netmod mailing list -- [email protected] To unsubscribe send an email to [email protected]
