On Wed, Feb 28, 2024 at 8:31 AM <mohamed.boucad...@orange.com> wrote:
> Hi Jan, > > > > Thanks for the comments. > > > > Here is a first attempt to address the long trees point while taking into > account expanded/unexpanded uses: > > > > NEW: > > YANG tree diagrams provide a concise representation of a YANG module > > and SHOULD be included to help readers understand YANG module > > structure. If the complete tree diagram for a module becomes too > > long, the diagram SHOULD be split into several smaller diagrams. If > > the complete tree diagram is too long even with groupings unexpanded > > (Section 2.2 of [RFC8340]), authors SHOULD NOT include it in the > > document. > > > > These guidelines take precedence over the generic guidance in > > Section 3 of [RFC8340]. > > > There may not be a natural split for multiple sections. It is not always clear what to do to implement this guideline. What is 'too long'? 1 page? 3 pages? 30 pages? I agree that the guideline needs to be updated to match the current style. Andy For convenience a diff for the proposed change can be seen > https://author-tools.ietf.org/api/iddiff?url_1=https://boucadair.github.io/rfc8407bis/draft-ietf-netmod-rfc8407bis.txt&url_2=https://boucadair.github.io/rfc8407bis/long-trees/draft-ietf-netmod-rfc8407bis.txt > > > > Cheers, > > Med > > > > *De :* Jan Lindblad <j...@tail-f.com> > *Envoyé :* mercredi 28 février 2024 15:21 > *À :* BOUCADAIR Mohamed INNOV/NET <mohamed.boucad...@orange.com> > *Cc :* netmod@ietf.org > *Objet :* Re: [netmod] Next steps for draft-ietf-netmod-rfc8407bis > > > > 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. > > > > + 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 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, mohamed.boucad...@orange.com 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 <i-d-announce-boun...@ietf.org> De la part de > internet-dra...@ietf.org > Envoyé : mercredi 28 février 2024 10:01 > À : i-d-annou...@ietf.org > Cc : netmod@ietf.org > 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 > netmod@ietf.org > https://www.ietf.org/mailman/listinfo/netmod > > > > ____________________________________________________________________________________________________________ > 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 > netmod@ietf.org > https://www.ietf.org/mailman/listinfo/netmod >
_______________________________________________ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
