[top-posting, as a contributor] I was discussing this issue with others during the Farewell reception.
The best idea that surfaced was: add to Datatracker the ability to upload a ".tgz" file "tgz" is a file format that extracts a directory hierarchy require that the extracted directory contains a well-defined entry point. this could be a file called "build.sh" or possibly "Makefile" the purpose of the entry point is to: validate examples (dynamically downloading dependencies) emit coverage statistics generate tree diagrams generate XML-file for `xml2rfc` (vis-a-vis Kramdown if needed). add to Datatracker the ability to also download the ".tgz" format of the document (if available) Of course, the ".tgz" could be 1-1 to a GitHub repo, but this solution stops short of mandating GitHub because: Datatracker generally handles artifacts (the ".tgz" file) Concern for incorporating 3rd-party infrastructure Kent > On Nov 17, 2025, at 11:01 AM, Rob Wilton (rwilton) > <[email protected]> wrote: > > Hi Camilo, > > I've added Mahesh/Med to the thread. I think that this is a conversation > that would need to be had with IANA or the RFC Editor. Arguably, I would > think that the RFC editor could/should be the long-term home for these > assets, but then that is not what is done with YANG Modules today, they are > instead hosted by IANA, so perhaps that is the more pragmatic choice. > > I definitely agree about storing them on Github whilst the draft is being > developed. Ideally, we would have some tooling that manages all of these. > This is similar what Med was doing with his YANG draft tooling project. It > is also similar to what I am doing for my drafts (but with different tooling > that I started earlier and with a fast compile/resolve step), e.g., > https://github.com/rgwilton/draft-yp-observability/ > > Here, I use a markdown file for the draft that imports the YANG examples, > YANG code, tree diagrams etc, and a build file > (https://github.com/rgwilton/draft-yp-observability/blob/main/build.mill) > that stitches everything together, after compiling and validating the YANG > and instance data examples, so if I update a YANG module and then save the > file, then the build tool will automatically detect the change, revalidate > the examples and report any errors, and then produce the updated html for the > draft. Tooling like this has some nice other properties since it will also > download and extract the YANG files from all the RFCs and drafts that I > depend on. When I get a bit of time, I will probably try and refine this > further, e.g., defining named schema associated with the instance data, > automatically build instance data file versions of the examples, etc. > > Kind regards, > Rob > > > From: Camilo Cardona <[email protected]> > Date: Monday, 17 November 2025 at 15:04 > To: Rob Wilton (rwilton) <[email protected]>, [email protected] > <[email protected]>, Carsten Bormann <[email protected]>, Kent Watsen > <[email protected]> > Cc: [email protected] <[email protected]> > Subject: Re: [netmod] Re: Should example modules be allowed to use code tags > [Re: AD review of draft-ietf-netmod-intf-ext-yang-16] > > Hi Rob, > > How complicated is to find that “permanent” home? Github is, of course, ruled > by a private company and I am not sure the process should depend on it.. We > could always keep it on github until the release process where the files are > then stored in the permanent home. > > Thanks, > Camilo > > From: "Rob Wilton (rwilton)" <[email protected]> > Date: Monday, 17 November 2025 at 04:37 > To: "[email protected]" <[email protected]>, Carsten Bormann > <[email protected]>, Kent Watsen <[email protected]> > Cc: "[email protected]" <[email protected]>, Camilo Cardona <[email protected]> > Subject: Re: [netmod] Re: Should example modules be allowed to use code tags > [Re: AD review of draft-ietf-netmod-intf-ext-yang-16] > > Hi Benoit, > > My proposal (and what I mentioned in the WG) was slightly different: > > I don't think that we should require complete examples in the RFC. > Specifically, I think that if we end up wrapping the examples with RFC 9195 > instance data + YANG library schema information, and bearing in mind the > short line lengths allowed in RFCs, I think that we will find "extra noise" > and a lot of line wrapping in the examples which will make them hard to read > and understand, defeating the purpose of putting them in the document in the > first place. > > I also don't think that we should putting the YANG modules into the RFCs, but > that is part of the separate Veloce discussion. > > What I propose is: > > Full compilable examples should be stored somewhere else, e.g., in GitHub, or > probably a more permanent home (e.g., IANA or RFC editor website). These > should contain or reference any necessary extra metadata (e.g., the > associated schema, or the contents of datastores if validating notifications). > > Examples in documents should just be there to aid the reader understand the > main structure of the module. They should be allowed to be incomplete, or > leave out long noisy fields (e.g., eliding long keys/hashes in some of the > crypto related drafts). However, the shorter examples in the draft should > include a reference/link to where the full validatable examples can be found. > > Kind regards, > Rob > > > From: [email protected] <[email protected]> > Date: Saturday, 15 November 2025 at 10:28 > To: Carsten Bormann <[email protected]>, Kent Watsen <[email protected]> > Cc: [email protected] <[email protected]>, Rob Wilton (rwilton) > <[email protected]>, Camilo Cardona <[email protected]> > Subject: Re: [netmod] Re: Should example modules be allowed to use code tags > [Re: AD review of draft-ietf-netmod-intf-ext-yang-16] > > Dear all, > > I am trying to summarize the conclusions of this email thread, in light of > the draft-cardona-claise-onion-yang-coverage > <https://datatracker.ietf.org/doc/draft-cardona-claise-onion-yang-coverage/> > presentation in the NETMOD meeting: > - We want to have instance examples next to the IETF YANG module. Granted > - We want to have those instance examples WITHIN the same document as the > YANG module. I guess so. > This is ideal but is it always possible, because there might be different > contexts? > See Rob Wilton's comment in the IETF 124 NETMOD meeting minutes > <https://datatracker.ietf.org/doc/minutes-124-netmod-202511071430/> > - I understand that the community would like a different tags for the > instances (next to CODE BEGINS/END) > And we have some in XML, great. > - What I am not sure: do we also need the tags for the text draft/RFC (next > to XML)? > > Where I would appreciate the help (of someone more clever that I): how to > practically add those tags, when you start from editing markdown draft. > A (process) example would be ideal. > > Thanks and regards, Benoit > > On Oct 13, 2025, at 16:30, Kent Watsen <[email protected]> > <mailto:[email protected]> wrote: > I find that the ASCII-armor CODE BEGINS/CODE ENDS is an undesirable relic > from days before XML-based RFCs. Now that RFCs are XML-native, better > constructs are possible. I do not think that extracting from Text-formatted > RFCs is necessary. Being able to extract from just XML is fine. Therefore I > do NOT support adding support for code-tags for examples. > RFCXML has markers= and related attributes name= etc. [1]; you never type > CODE BEGINS/ENDS. > There is no need to ever apply heuristics to pull source from plaintext > renderings any more. > > Try kramdown-rfc-extract-sourcecode on the XML if you need a tool. > Try https://tzi.de/~cabo/i-d or /rfc for a prototype of the “RFC filesystem” > I’m proposing (not recently updated though). > > Grüße, Carsten > > [1]: https://authors.ietf.org/rfcxml-vocabulary#markers > > _______________________________________________ > netmod mailing list -- [email protected] <mailto:[email protected]> > To unsubscribe send an email to [email protected] > <mailto:[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]
