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

[[e-mail]]

Hi Andy, all,

I updated the text to indicate that


  *   “Long” = exceeds 2 pages typically,
  *   “Too long” = exceeds 5 pages
  *   Short subtree: fits within a page

Cheers,
Med

De : Andy Bierman <[e-mail]>
Envoyé : mercredi 28 février 2024 19:26
À : BOUCADAIR Mohamed INNOV/NET <[e-mail]>
Cc : Jan Lindblad <[e-mail]>; [e-mail]
Objet : Re: [netmod] Long trees RE: Next steps for draft-ietf-netmod-rfc8407bis



On Wed, Feb 28, 2024 at 8:31 AM <[e-mail]<mailto:[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]<mailto:[e-mail]>>
Envoyé : mercredi 28 février 2024 15:21
À : BOUCADAIR Mohamed INNOV/NET <[e-mail]<mailto:[e-mail]>>
Cc : [e-mail]<mailto:[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]<mailto:[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]<mailto:[e-mail]>> De la part de
[e-mail]<mailto:[e-mail]>
Envoyé : mercredi 28 février 2024 10:01
À : [e-mail]<mailto:[e-mail]>
Cc : [e-mail]<mailto:[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<https://data/>
tracker.ietf.org<http://tracker.ietf.org/>%2Fdoc%2Fdraft-ietf-netmod-
rfc8407bis%2F&data=05%7C02%7Cmohamed.boucadair%40orange.com<http://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<https://www/>.
ietf.org<http://ietf.org/>%2Farchive%2Fid%2Fdraft-ietf-netmod-rfc8407bis-
09.html&data=05%7C02%7Cmohamed.boucadair%40orange.com<http://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<https://auth/>
or-tools.ietf.org<http://or-tools.ietf.org/>%2Fiddiff%3Furl2%3Ddraft-ietf-netmod-rfc8407bis-
09&data=05%7C02%7Cmohamed.boucadair%40orange.com<http://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]<mailto:[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]<mailto:[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.