On Tue, Sep 30, 2025 at 9:23 AM Rob Wilton (rwilton) <[email protected]> wrote:
> 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. > > > I am in favor of some new type of RFC markup or tooling that allows automatic validation of instance data examples and code coverage reporting. RFC text can get complex. The YANG uses and augment expansion can get complex. Often, a correct example is the only way to get the developer to understand the data structure. It is possible that instance data validation is part of the 'build' phase and is not included in the output at all. IMO, it would be useful to test tools to have some valid examples. More than a filename is needed here. The target data node for the instance data is also needed. Looks like ONIONS WG-to-be has already started the code coverage work: https://www.ietf.org/archive/id/draft-cardona-claise-onion-yang-coverage-00.html E.g for NACM example: https://datatracker.ietf.org/doc/html/rfc8341#appendix-A.2 <EXAMPLE BEGINS target "/ietf-netconf-acm:nacm" file "nacm-example-1.xml"> // nacm example in RFC 8341 <EXAMPLE ENDS> Kind regards, > Rob > Andy > > > > > *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]> 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]> wrote: > > > > On Wed, Sep 24, 2025 at 4:26 AM tom petch <[email protected]> wrote: > > From: Mahesh Jethanandani <[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]
