On Fri, Oct 3, 2025 at 8:46 AM Camilo Cardona <[email protected]> wrote:
> Here I guess you mean both yang module examples and yang instance examples? > > > Yes. RFC 8407 (and bis) clearly states that CODE BEGINS is only for normative modules. This draft does not mention instance document examples as code components. It is possible to validate example modules and instance documents as part of the build process. Extraction is desirable, but not required. It's unfortunate that the IETF cannot utilize modern tools like Sphinx, Pygments, and RST. The 'code-block' approach is easy to use and solves the validation problem. Andy On 3 Oct 2025, at 10:25, Andy Bierman <[email protected]> wrote: > > > > On Fri, Oct 3, 2025 at 4:56 AM tom petch <[email protected]> wrote: > >> 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)." >> >> > https://datatracker.ietf.org/doc/html/rfc8407#section-3.2.1 > Section 3.2.1 was added in RFC 8407, and this change was made in 8407bis. > > IMO, a code component must be normative. It doesn't have to be a YANG > module. > It is intended to meet various requirements (e.g. contains IETF Trust > copyright). > > Examples are not code components. > Invent something new. Pick a different name than CODE. > > > > 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 >> . >> > > What parts of 8407bis will require migration? > Do you mean the Semver changes in a different draft? > > > >> Tom Petch >> >> > > Andy > > >> >> 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] > > >
_______________________________________________ netmod mailing list -- [email protected] To unsubscribe send an email to [email protected]
