Re: [netmod] Long trees RE: Next steps for draft-ietf-netmod-rfc8407bis

[Andy Bierman <[e-mail]>]

On Wed, Feb 28, 2024 at 8:31 AM <[e-mail]> 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 <[e-mail]>
> *Envoyé :* mercredi 28 février 2024 15:21
> *À :* BOUCADAIR Mohamed INNOV/NET <[e-mail]>
> *Cc :* [e-mail]
> *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, [e-mail] 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 <[e-mail]> De la part de
> [e-mail]
> Envoyé : mercredi 28 février 2024 10:01
> À : [e-mail]
> Cc : [e-mail]
> 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
> [e-mail]
> 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
> [e-mail]
> https://www.ietf.org/mailman/listinfo/netmod
>