Hi Jan, > On Feb 28, 2024, at 9:21 AM, Jan Lindblad <[email protected]> wrote: > > Med, author team, > > Thank you for taking the time to get this work done, and well done! This is > one of those fundamental bricks that saves time and improves quality for the > entire YANG community. > > I read the -09 version and like what I see. I have a couple of minor > suggestions you might consider. > > + In section 3.4 about tree diagrams, the section text is already advocating > intermixing smaller tree snippets with explanations (which is great), but I > wish we could say that > tree diagrams of entire modules SHOULD NOT be included. Just a waste of > forest and attention span, imho.
The client-server suite of drafts takes this idea a step further, by many times using unexpanded tree-diagrams, along with associated hyperlinks to where the grouping was defined. For instance: https://datatracker.ietf.org/doc/html/draft-ietf-netconf-tls-client-server#section-4.1.2.1 > + In section 4.2 about choice of prefixes, it is said that "Prefix values > SHOULD be short but are also likely to be unique." I used to say the same > thing. In recent years, however, I have started to stress the importance of > uniqueness much more. I'd say something like "Prefix values SHOULD be > selected carefully to be unique, and ideally not too long." The reason for my > change is I have met several engineers who have been deeply confused (to the > point of costing real money) when the same prefix has shown up in multiple > places. It's just an unnecessary part of the learning curve associated with > YANG. > > In fact, I have started to recommend people to set the prefix to equal the > module name. This also solves another problem, which is that the "prefixes" > you see in RESTCONF are module names, and the confusion of what to use where > is sometimes suffocating. I understand if many think I'm going overboard > here, but when we pretend that modules don't have prefixes, only module > names, there is a lot less friction in learning the ropes. In my private modules, I’ve taken to setting the prefix to be the same as the module name. The clarity is great, and I don’t see an issue with the verbosity. Something to consider? Kent > + In section 4.6.2 regarding useless (in YANG Context) functions in the XPath > function library, it is said that the "YANG compiler" should return false, > etc. Better wording might be that the XPath execution environment (or > something) should return false, etc. The YANG compiler is not even running > when the calls to those functions are happening. > > + In section 4.11.5 regarding booleans, it is said that booleans can take > values true and false. This is true in mathematics :-) but in YANG a boolean > leaf can additionally take the "value" of "not set". Actually, "not set" is a > possibility for leafs in general, unless it is declared mandatory true, or > has a default. In my experience, one of the most common YANG modeling issues > is when people model a leaf foo, which isn't mandatory, has no default and > the description statement does not say what happens if the leaf is not set. > In many cases, there is a sort of natural meaning, but with booleans leafs in > particular, the absence of the leaf is typically highly ambiguous. I think > this hole merits a recommendation clause in the I-D. > > Best Regards, > /jan > > > >> On 28 Feb 2024, at 10:51, [email protected] wrote: >> >> Hi all, >> >> I think that this version is ready for the WGLC. >> >> The document fully covers the items promised when requesting adoption [1]. >> As listed in the ACK section, we also solicited and integrated feedback from >> many yangdoctors, solicited SAAG WG to review the security text, etc. Refer >> to 1.1 for a comprehensive list of the changes. >> >> Cheers, >> Med >> >> [1] Slide#7 of >> https://datatracker.ietf.org/meeting/117/materials/slides-117-netmod-7-guidelines-for-authors-and-reviewers-of-documents-containing-yang-data-models-00 >> >> >>> -----Message d'origine----- >>> De : I-D-Announce <[email protected]> De la part de >>> [email protected] >>> Envoyé : mercredi 28 février 2024 10:01 >>> À : [email protected] >>> Cc : [email protected] >>> Objet : I-D Action: draft-ietf-netmod-rfc8407bis-09.txt >>> >>> Internet-Draft draft-ietf-netmod-rfc8407bis-09.txt is now available. >>> It is a work item of the Network Modeling (NETMOD) WG of the IETF. >>> >>> Title: Guidelines for Authors and Reviewers of Documents >>> Containing YANG Data Models >>> Authors: Andy Bierman >>> Mohamed Boucadair >>> Qin Wu >>> Name: draft-ietf-netmod-rfc8407bis-09.txt >>> Pages: 84 >>> Dates: 2024-02-28 >>> >>> Abstract: >>> >>> This memo provides guidelines for authors and reviewers of >>> specifications containing YANG modules, including IANA-maintained >>> modules. Recommendations and procedures are defined, which are >>> intended to increase interoperability and usability of Network >>> Configuration Protocol (NETCONF) and RESTCONF protocol >>> implementations that utilize YANG modules. This document obsoletes >>> RFC 8407. >>> >>> Also, this document updates RFC 8126 by providing additional >>> guidelines for writing the IANA considerations for RFCs that >>> specify >>> IANA-maintained modules. >>> >>> The IETF datatracker status page for this Internet-Draft is: >>> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdata >>> tracker.ietf.org%2Fdoc%2Fdraft-ietf-netmod- >>> rfc8407bis%2F&data=05%7C02%7Cmohamed.boucadair%40orange.com%7C51672231 >>> 30c943a5a4c608dc383bce6b%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C >>> 638447076716455966%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjo >>> iV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=s5VX9Hb%2Fl >>> P9v5QurysF69syyEyba9yYss7xd7K5E2FE%3D&reserved=0 >>> >>> There is also an HTML version available at: >>> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww. >>> ietf.org%2Farchive%2Fid%2Fdraft-ietf-netmod-rfc8407bis- >>> 09.html&data=05%7C02%7Cmohamed.boucadair%40orange.com%7C5167223130c943 >>> a5a4c608dc383bce6b%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C638447 >>> 076716464395%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luM >>> zIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=%2Br3nHahSq8OV24f >>> hFxBkJaqY43Q0GUxcbPZSFhji4uk%3D&reserved=0 >>> >>> A diff from the previous version is available at: >>> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fauth >>> or-tools.ietf.org%2Fiddiff%3Furl2%3Ddraft-ietf-netmod-rfc8407bis- >>> 09&data=05%7C02%7Cmohamed.boucadair%40orange.com%7C5167223130c943a5a4c >>> 608dc383bce6b%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C63844707671 >>> 6470644%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLC >>> JBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=zo%2FrtFJrYJkJXOceIpzR >>> mlGAQF2c8m9Z%2F0vShl5o8gQ%3D&reserved=0 >>> >>> Internet-Drafts are also available by rsync at: >>> rsync.ietf.org::internet-drafts >>> >> >> >> ____________________________________________________________________________________________________________ >> Ce message et ses pieces jointes peuvent contenir des informations >> confidentielles ou privilegiees et ne doivent donc >> pas etre diffuses, exploites ou copies sans autorisation. Si vous avez recu >> ce message par erreur, veuillez le signaler >> a l'expediteur et le detruire ainsi que les pieces jointes. Les messages >> electroniques etant susceptibles d'alteration, >> Orange decline toute responsabilite si ce message a ete altere, deforme ou >> falsifie. Merci. >> >> This message and its attachments may contain confidential or privileged >> information that may be protected by law; >> they should not be distributed, used or copied without authorisation. >> If you have received this email in error, please notify the sender and >> delete this message and its attachments. >> As emails may be altered, Orange is not liable for messages that have been >> modified, changed or falsified. >> Thank you. >> >> _______________________________________________ >> netmod mailing list >> [email protected] >> https://www.ietf.org/mailman/listinfo/netmod >> > > _______________________________________________ > netmod mailing list > [email protected] > https://www.ietf.org/mailman/listinfo/netmod _______________________________________________ netmod mailing list [email protected] https://www.ietf.org/mailman/listinfo/netmod
