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]
